# Navbar ## Overview

Navbar demo

A **Navbar** in Servoy is a **horizontal navigation bar** typically placed at the top of the application interface. It is used to provide users with quick access to major sections or features of the application. The navbar often contains links or buttons that allow users to navigate between different forms or pages in a consistent and intuitive manner. Navbars are commonly used in applications to enhance user experience by offering easy access to global navigation options like `Home`, `Dashboard`, `Settings`, and more. They can also contain additional elements like dropdowns, search fields, and icons for notifications, user profiles, or other utility actions. The Navbar component wraps a bootstrap navbar (see [here](https://getbootstrap.com/docs/5.3/components/navbar/) for details) into a component usable directly from within Servoy. **Key Features of a Navbar**: * **Horizontal Layout**: The navbar provides a horizontal layout for navigation items, usually placed at the top of the application. This layout ensures that major sections of the application are always visible and accessible. * **Navigation Links**: The navbar contains buttons or links that allow users to navigate to different forms or sections of the application. These links can represent different views or modules, such as Dashboard, Reports, or Settings. * **Dropdown Menus**: The navbar can include dropdown menus for nested or grouped navigation options. This is useful when you want to offer multiple related options under a single menu item, such as user settings or report types. * **Search Field**: Navbars often include a search input field to allow users to quickly search through the application or specific data, providing a more comprehensive and functional navigation experience. * **Utility Icons**: Navbars may also include icons for additional utilities such as notifications, messages, or profile settings. These icons typically have contextual dropdowns or links associated with them. * **Responsive Design**: In responsive layouts, the navbar can adapt to different screen sizes, collapsing into a hamburger menu on smaller screens to save space while still providing easy access to the navigation items. ## Use Cases for Navbar * **Global Application Navigation**: In applications with global sections (e.g., Dashboard, Reports, Settings), the navbar provides quick access to these areas while maintaining consistency across the interface. * **Modular Systems**: For modular systems like admin dashboards or content management systems, the navbar allows users to easily switch between modules or sections. * **User Profile and Utility Actions**: The navbar is ideal for placing user-related actions like profile management, notifications, settings, and logout. These can be accessed through icons or dropdowns. * **Responsive Applications**: In responsive applications, the navbar can collapse into a hamburger menu for mobile or tablet users, making navigation accessible without taking up too much screen space. ## Get Started ### Creating a Navbar component

Create a Navbar

Here are the steps for creating a Navbar: 1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor.md) of the form where you need to place a **Navbar** component 2. Find **Navbar** in *Navigation* section in the components' pallet 3. Drag and drop the **Navbar** component in the desired place of the form 4. Set the menu items; this can be done via [properties panel](#setting-the-menu-items-in-the-properties-panel) 5. Edit other [**Navbar** properties](/reference/servoyextensions/ui-components/navigation/navbar.md#properties) and [**Navbar menu item** properties](/reference/servoyextensions/ui-components/navigation/navbar.md#menuitem) *** {% hint style="info" %} **Hint** Create a Navbar through a Servoy Menu In case there is an existing [Servoy Menu](/guides/develop/application-design/data-modeling/menu.md#overview) that will be used as a Navbar menu, then here are the steps to be followed: 1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor.md) of the form where you need to place a **Navbar** component 2. Find the desired Servoy Menu name in the *Servoy Menu* section in the components' palette 3. Drag and drop the desired Servoy Menu name in the form. This will open the [JSMenu compatible component selector](/reference/servoy-developer/object-editors/jsmenu-compatible-component-selector.md#overview) 4. Select `Navbar[bootstrapextracomponents]` option, then click `OK`. This will add to the main form a Sidenav component having the desired Servoy Menu name set for [servoyMenu](/reference/servoyextensions/ui-components/navigation/sidenav.md#servoymenu) property of the component 5. Configure [**Navbar** properties](/reference/servoyextensions/ui-components/navigation/navbar.md#properties) in the component's properties panel. If needed, you can change or remove the assigned [servoyMenu](/reference/servoyextensions/ui-components/navigation/sidenav.md#servoymenu). In this case, you must manually configure the [**Navbar menu item** properties](/reference/servoyextensions/ui-components/navigation/navbar.md#menuitem). {% endhint %} ## Setting the Menu The **Navbar** component supports two ways to configure its menu: 1. **Using** [**`servoyMenu`**](/reference/servoyextensions/ui-components/navigation/sidenav.md#servoymenu) **property**: Assign a predefined [servoyMenu](/guides/develop/application-design/data-modeling/menu.md#overview) for centralized menu management. 2. **Using** [**`menu`**](/reference/servoyextensions/ui-components/navigation/navbar.md#menuitems) **property**: Manually define menu items directly inside the component. {% hint style="info" %} **Using either a manually configured menu or servoyMenu will not change the appearance of the Navbar.**\ Both methods result in the **same** UI layout, styling, and interactions, including menu item rendering, nested structures, icons, and animations. The only difference is in how the menu items are configured and managed. {% endhint %} {% hint style="danger" %} **IMPORTANT!**\ If **both methods** are used, the manually configured menu **will take precedence**, and the **servoyMenu will be ignored**. {% endhint %} ### Assigning an existing servoyMenu Instead of configuring the menu manually, you can assign a **predefined** [**servoyMenu**](/guides/develop/application-design/data-modeling/menu.md#overview) in Navbar [`servoyMenu`](/reference/servoyextensions/ui-components/navigation/navbar.md#servoymenu) property, which allows you to: * Centrally manage menus across multiple components. * Easily update menus without modifying individual Sidenav components. * Use the same menu structure in different parts of the application. To assign a `servoyMenu`: 1. In the Properties Panel of the **Navbar** component, locate the [`servoyMenu`](/reference/servoyextensions/ui-components/navigation/navbar.md#servoymenu) property and click on its value. This will open the [Servoy Menu Selection Wizard](/reference/servoy-developer/object-editors/menu-selection-wizard.md#overview) 2. Select an existing `servoyMenu` from the list. 3. When a `servoyMenu` is assigned, its menu items are automatically applied to the Navbar component. ### Setting the menu items in the properties panel

Adding and editing menu items and sub menu items

You can configure menu items directly in the **Navbar** [**`menuItems`**](/reference/servoyextensions/ui-components/navigation/navbar.md#menuitems) **property**. This allows fine-grained control over the menu structure, including: * Adding menu items manually. * Defining sub-menus (up to 4 levels deep). * Setting icons, styles, and form associations. After dragging the component on the form, find the **Navbar** in the form editor, click it and proceed with the following steps: 1. Add a menu item: * Select the [`menuItems`](/reference/servoyextensions/ui-components/navigation/navbar.md#menu) property and click the `+` button in order to add a menu item. Next menu item can be added the same way or by clicking the `+` button (`insert a new array item below`) of another menu item. 2. Expand the [`menuItems`](/reference/servoyextensions/ui-components/navigation/navbar.md#menu) property to see the list of menu items. They are also shown in the **Navbar** component (in the form editor) 3. In order to edit each menu item, expand it in the Properties Panel and set its [properties](/reference/servoyextensions/ui-components/navigation/navbar.md#menuitem) {% hint style="info" %} **Navbar menu items**\ It is necessary to set an unique id in the Navbar **menu item** [id](/reference/servoyextensions/ui-components/navigation/navbar.md#menuitem) property.\ Example: `home_page`. {% endhint %} ## Working with Navbar A Navbar is a simple navigation bar that offers: * an optional branding logo on the left * an optional branding text on the left * two bars with any number of items * plain texts * single clickable menu entries * dropdown menus showing a menu (one level) * buttons * text fields (optionally as type aheads) One of the two bars is aligned to the left, the other to the right. Either one or both can be set. Each item in the bar is a [MenuItem](#menuitem-type) javascript object with a `position` (`LEFT` or `RIGHT`) and a `displayType` (e.g. `BUTTON`) that controls how the single entry is displayed. Depending on the `displayType` a MenuItem's properties can have component specific meaning (for example the text property is used as placeholder text for an input field). You can find a list of Navbar **properties** [here](/reference/servoyextensions/ui-components/navigation/navbar.md#properties). ### Setting the Brand Navbar has a few properties that allow setting and customizing branding logo and text: * [`brandLogo`](/reference/servoyextensions/ui-components/navigation/navbar.md#brandlogo): an optional media shown as branding logo in the upper left corner. * [`brandLogoStyleClass`](/reference/servoyextensions/ui-components/navigation/navbar.md#brandlogostyleclass): optional style class(es) that can be added to the brandLogo media. * [`brandLogoTabindex`](/reference/servoyextensions/ui-components/navigation/navbar.md#brandlogotabindex): sets the tab index for brand logo * [`brandText`](/reference/servoyextensions/ui-components/navigation/navbar.md#brandtext): an optional branding text shown in the upper left corner (after the optional brandLogo) * [`brandTextTabindex`](/reference/servoyextensions/ui-components/navigation/navbar.md#brandtexttabindex): sets the tab index for brand text ### Set the Navbar's position Navbar's position can be set in [fixed](/reference/servoyextensions/ui-components/navigation/navbar.md#fixed) property. This property controls whether the toolbar is fixed to either top or bottom of the screen. ### Distinct Active Menu Item Setting the [markClickedItemActive](/reference/servoyextensions/ui-components/navigation/navbar.md#markclickeditemactive) property to `true`, items of `displayType`: `MENU_ITEM` will be shown as "active" when clicked. ### Setting menu item's properties A complete list of menu item's properties can be found [here](/reference/servoyextensions/ui-components/navigation/navbar.md#menuitem). Properties to be set: * `item`: Identifier of a menu item. This property is required to allow the component to figure out what item a user selected * `text`: The text shown. Is used as placeholder text on INPUT or INPUT\_GROUP items * `displayType`: Controls the appearance of the menu item: * `MENU_ITEM` (default) * `TEXT` * `BUTTON` * `INPUT` * `INPUT_GROUP` * `subMenuItems`: An optional array of sub menus for a `MENU_ITEM` type. When set, the item will be shown as a dropdown * `enabled`: enables the menu item * `iconName`: An optional icon added to the menu item. Any glyhicon or font awesome icon can be used (e.g. "glyphicon glyphicon-search" or "fa fa-car"). When used with `INPUT` or `INPUT_GROUP` used as the button's icon. * `inputButtonStyleClass`: Style class to control the optional button shown with `INPUT` or `INPUT_GROUP`. Typically one of bootstraps button classes ("btn-default", "btn-primary", "btn-success", "btn-info", "btn-warning", "btn-danger", "btn-link"). Default is "btn-default" * `isActive`: When `true`, a `MENU_ITEM` item will be shown as `active` * `position`: Controls whether an item is shown on the left or on the right of the navbar. Default is `LEFT` * `styleClass`: Additional style class(es) of the component * `tooltip`: An optional tooltip for the item * `valuelist`: When set, an `INPUT` or `INPUT_GROUP` item will show a typeahead list. * `onAction`: Function that will be called if the item is clicked on (`MENU_ITEM`, `BUTTON`), a submenu is selected (`MENU_ITEM` with `subMenuItems`) or the user hits enter, leaves the field or clicks the optional button (`INPUT`, `INPUT_GROUP`). If not set, the component will call the `onMenuItemClicked` method assigned to the component itself. ### Menu Item DisplayType Menu item `displayType` property has the following options: #### DisplayType: `MENU_ITEM` (default) Simple clickable entry in the navbar. Example with just the text:

MenuItem Text

Example with icon and submenus:

MenuItem Dropdown

Example of an opened submenu:

MenuItem Dropdown opened

For an item of `displayType`:`MENU_ITEM` the `MenuItem` properties are used as:
PropertyUsage
dataProvidernot used
iconNameicon to the left of the entry's name
inputButtonStyleClassnot used
inputButtonTextnot used
subMenuItemsWhen set, the item will be shown as a dropdown menu
valuelistnot used
onActionFired when the user clicks on the item or selects an item from the dropdown menu
*** #### DisplayType: `TEXT` Plain text shown in the bar:

Text

For an item of `displayType`:`TEXT` the `MenuItem` properties are used as:
PropertyUsage
dataProvidernot used
iconNameicon to the left of the entry's name
inputButtonStyleClassnot used
inputButtonTextnot used
subMenuItemsnot used
valuelistnot used
onActionnot fired
*** #### DisplayType: `BUTTON` A normal button. Example with text "Button 1", iconName "glyphicon glyphicon-camera" and styleClass "btn-primary":

Button

For an item of `displayType`:`BUTTON` the `MenuItem` properties are used as:
PropertyUsage
dataProvidernot used
iconNameicon to the left of the entry's name
inputButtonStyleClassnot used
inputButtonTextnot used
subMenuItemsnot used
valuelistnot used
onActionfired when the user clicks on an item
styleClassButton style class. Typically one of bootstraps button classes ("btn-default", "btn-primary", "btn-success", "btn-info", "btn-warning", "btn-danger", "btn-link"). Default is "btn-default".
*** #### DisplayType: `INPUT` An item of type `INPUT` adds a text field to the navbar. The text field can have an optional button grouped next to it when the `inputButtonText` or `iconName` (or both) property is set. Example with iconName and inputButtonText:

Input

For an item of `displayType`:`INPUT` the `MenuItem` properties are used as:
PropertyUsage
dataProviderused to assign the dataprovider of the field
iconNameWhen set a button with that icon is shown next to the input field. Any glyhicon or font awesome icon can be used (e.g. "glyphicon glyphicon-search" or "fa fa-car").
inputButtonStyleClassUsed for the optional button. Typically one of bootstraps button classes ("btn-default", "btn-primary", "btn-success", "btn-info", "btn-warning", "btn-danger", "btn-link"). Default is "btn-default".
inputButtonTextWhen set a button with the text is shown next to the input field.
subMenuItemsnot used
valuelistWhen set, the input will show a typeahead list.
onActionfired when the user hits enter in the field, leaves the field or clicks on the optional button next to the field.
*** #### DisplayType: `INPUT_GROUP` An item of type `INPUT_GROUP` behaves the same as `INPUT` except that the field is rendered along with optional button as an `inputgroup`. There is no spacing between the field and the button. Example with `iconName` and `inputButtonText`:

Inputgroup

## Scripting Navbar ### Main events You can find a list of Navbar **events** [here](/reference/servoyextensions/ui-components/navigation/navbar.md#events).\ You can find a list of Navbar **API methods** [here](/reference/servoyextensions/ui-components/navigation/navbar.md#api). Let's consider the following setup: * `main_form`: the form where the Navbar component is placed, together with a [form container](/guides/develop/application-design/forms/form-containers/form-container.md#overview) component, `fc_nav` * Navbar component has the following menu items: * `item`:`home`, `displayName`:`Home` * `item`:`menu_item1`, `displayName`:`Menu Item #1` * `item`:`menu_item2`, `displayName`:`Menu Item #2` * `item`:`menu_item3`, `displayName`:`Menu Item #3` * separate forms showed in `main_form` as a contained form in the form container component: `home`, `menu_item1`, `menu_item2`, `menu_item3`. ### onBrandClicked This event is called when the user clicks on the brand logo or text.\ Here is an example of how to use the [onBrandClicked](/reference/servoyextensions/ui-components/navigation/navbar.md#onbrandclicked) event of Navbar in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor.md).\ The following goes on `main_form` script file: ```javascript /** * Called when the user clicks on the brand logo or text. * * @param {JSEvent} event * * @private * * @properties={typeid:24,uuid:"A122138E-AA11-4570-9A94-C1C7454C579D"} */ function onBrandClicked(event) { elements.fc_nav.containedForm = forms.home; // shows the `Home` form in the form container when clicking on brand logo or text } ``` ### onMenuItemClicked This event is called when a menu item is clicked.\ Here is an example of how to use the [onMenuItemClicked](/reference/servoyextensions/ui-components/navigation/navbar.md#onmenuitemclicked) event of Navbar in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor.md). The following goes on `main_form` script file: ```javascript /** * Called whenever a menu item is clicked or a submenu item is selected with the JSEvent and the menuItem object clicked on. * * @param {JSEvent} event * @param {CustomType} menuItem * * @private * * @properties={typeid:24,uuid:"6F2D94B3-C80F-4086-976C-0DAFBF05E256"} */ function onMenuItemClicked(event, menuItem) { elements.fc_nav.containedForm = forms[menuItem.itemId] // menuItem.itemId gets the ID value of the clicked menu item } ``` ### Setting menu items for a manually configured component's menu Sets all menu items of the navbar. The branding remains untouched.\ Here is an example of how to use the [setMenuItems](/reference/servoyextensions/ui-components/navigation/navbar.md#setmenuitems) event of Navbar in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor.md): ```javascript var menuItems = []; menuItems.push({itemId: '1', text: 'Accounts', tooltip: 'Accounts'}); menuItems.push({itemId: '2', text: 'Invoices', tooltip: 'Invoices'}); menuItems.push({itemId: '3', text: 'Click me', displayType: 'BUTTON', tooltip: 'Button'}); menuItems.push({text: 'Payables', tooltip: 'Payables'}); menuItems.push({itemId: '5', text: 'Search account...', displayType: 'INPUT', iconName: 'glyphicon glyphicon-search', tooltip: 'Search'}); menuItems.push({itemId: '6', text: 'Menu', position: 'RIGHT', tooltip: 'A submenu', subMenuItems: [{itemId: '6.1', text: 'Action'}, {itemId: '6.2', text: 'More action'}, {isDivider: true}, {itemId: '6.3', text: 'Last action'}]}); menuItems.push({itemId: '7', text: 'Logged in as John Doe', tooltip: 'just text', displayType: 'TEXT', position: 'RIGHT'}); elements.navbar.brandText = 'Accounting'; elements.navbar.setMenuItems(menuItems); ``` ### Add a menu item Adds the given item to the navbar. Here is an example of how to use the [addMenuItem](/reference/servoyextensions/ui-components/navigation/navbar.md#addmenuitem) event of Navbar in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor.md): **For a manually configured Menu:** ```javascript /** @type {bootstrapextracomponents-navbar.menuItem} */ var itemToAdd = { itemId: application.getUUID().toString(), text: 'Item added' } elements.navbar.addMenuItem(itemToAdd); ``` *** **For an assigned servoyMenu:** ```javascript // Get reference to servoyMenu var menu = elements.navbar.servoyMenu; // Create a new menu item var newItem = menu.addMenuItem("item1"); newItem.menuText = "Sample Item #1"; ``` ### Remove menu Item Removes the item with the given `itemId` from the bar.\ Here is an example of how to use the [removeMenuItem](/reference/servoyextensions/ui-components/navigation/navbar.md#removemenuitem) event of Navbar in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor.md): **For a manually configured Menu:** ```javascript /** * Fired when the button is clicked. * * @param {JSEvent} event * * @private * * @properties={typeid:24,uuid:"01F79B4C-917A-44A6-8499-F99D4611FA5F"} */ function onAction$remove(event) { elements.navbar.removeMenuItem(`menu_item3`); // `menu_item3` is the id of the item we want to remove from the menu } ``` *** **For an assigned servoyMenu:** ```javascript // Get reference to servoyMenu var menu = elements.navbar.servoyMenu; // remove menu item menu.removeMenuItem("menu_item3") // `menu_item3` is the id of the item we want to remove from the menu ``` ### Set selected menu item Sets the item with the given ID as selected (sets the `isActive` property). Items of type `MENU_ITEM` will be rendered with a different background color when selected. Here is an example of how to use the [setMenuSelected](/reference/servoyextensions/ui-components/navigation/navbar.md#setmenuselected) event of Navbar in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor.md): **For a manually configured Menu:** ```javascript /** * Fired when the button is clicked. * * @param {JSEvent} event * * @private * * @properties={typeid:24,uuid:"01F79B4C-917A-44A6-8499-F99D4611FA5F"} */ function onAction$setMenuSelected(event) { elements.navbar.setMenuSelected(`menu_item3`); // `menu_item3` is the id of the item we want to set as selected - active } ``` *** **For an assigned servoyMenu:** ```javascript // Get reference to servoyMenu var menu = elements.navbar.servoyMenu; // remove menu item menu.selectMenuItem("menu_item3") // `menu_item3` is the id of the item we want to set as selected - active ``` ### Get the selected menu item Returns the currently selected menu item.\ Here is an example of how to use the [getSelectedMenu](/reference/servoyextensions/ui-components/navigation/navbar.md#getselectedmenu) event of Navbar in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor.md): **For a manually configured Menu:** ```javascript /** * Fired when the button is clicked. * * @param {JSEvent} event * * @return {CustomType} selected * * @private * * @properties={typeid:24,uuid:"01F79B4C-917A-44A6-8499-F99D4611FA5F"} */ function onAction$getSelectedMenu(event) { var selected = elements.navbar.getSelectedMenu(); // Returns the currently selected menu item return selected; } ``` *** **For an assigned servoyMenu:** ```javascript // Get reference to servoyMenu var menu = elements.navbar.servoyMenu; // remove menu item menu.getSelectedItem() // Returns the currently selected menu item ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.servoy.com/guides/develop/application-design/ui-components/navigation/navbar.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.