A **Sidenav** (short for side navigation) in Servoy is a UI component that provides a **vertical navigation menu** typically placed on the left (or sometimes right) side of an application interface. Sidenav allows users to navigate quickly between different sections or forms within the application. This type of navigation is common in modern web and mobile applications, providing a consistent and intuitive structure, particularly when managing multiple sections or forms.
**Key Features of Sidenav**:
* **Multi-Level Navigation (Up to 4 Levels)**: The sidenav can manage nested items up to 4 levels deep. Each level can have selectable and collapsible items, where one item can be selected and expanded at a time.
* **Collapsible and Expandable Menu Items**: Menu items within the sidenav can be collapsed or expanded, giving users control over how much information is visible at any given time. When an item is selected, its child items (if any) are automatically expanded.
* **Programmatic Control**: The sidenav component can be controlled programmatically, allowing developers to modify its runtime properties and trigger actions through the component's API.
* **Form Container Integration**: The sidenav can serve as a form container that displays a form alongside the menu. This form animates together with the menu when it slides in or out, creating a seamless user experience.
## Use Cases for Sidenav
* **Multi-Section Applications**: In applications with multiple sections or areas (such as an admin panel, content management system, or e-commerce platform), a sidenav provides a clear, structured way to navigate between forms or modules.
* **Hierarchical Navigation**: For applications that require deep, hierarchical navigation (e.g., categories and subcategories in a product catalog), sidenav is ideal for letting users drill down into different levels of the hierarchy.
* **Responsive Design**: In mobile and responsive applications, the sidenav can be made collapsible or hidden on smaller screens, giving users access to navigation when needed while conserving screen space.
## Get Started
### Creating a Sidenav component
Create a Sidenav
Here are the steps for creating a Sidenav:
1. Open the [Form Editor](/reference/servoy-developer/object-editors/form-editor.md) of the form where you need to place a **Sidenav** component
2. Find **Sidenav** in the *Navigation* section in the components' palette
3. Drag and drop the **Sidenav** component in the desired place of the form
4. [Set the menu](#setting-the-menu)
5. Edit other [**Sidenav** properties](/reference/servoyextensions/ui-components/navigation/sidenav.md#properties) and [**Sidenav menu item** properties](/reference/servoyextensions/ui-components/navigation/sidenav.md#menuitem), if the case
***
{% hint style="info" %}
**Hint**
In case there is an existing [Servoy Menu](/guides/develop/application-design/data-modeling/menu.md#overview) that will be used as a Sidenav 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 **Sidenav** 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 `sidenav[servoyextra]` 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 [**Sidenav** properties](/reference/servoyextensions/ui-components/navigation/sidenav.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 [**Sidenav menu item** properties](/reference/servoyextensions/ui-components/navigation/sidenav.md#menuitem).
{% endhint %}
## Setting the Menu
The **Sidenav** 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/sidenav.md#menu) **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 Sidenav.**\
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 Sidenav [`servoyMenu`](/reference/servoyextensions/ui-components/navigation/sidenav.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 **Sidenav** component, locate the [`servoyMenu`](/reference/servoyextensions/ui-components/navigation/sidenav.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 Sidenav 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 **Sidenav** [**`menu`**](/reference/servoyextensions/ui-components/navigation/sidenav.md#menu) **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 **Sidenav** in the form editor, click it and proceed with the following steps:
1. Add a menu item:
* Select the [`menu`](/reference/servoyextensions/ui-components/navigation/sidenav.md#menu) property and click the `+` button in order to add a menu item. You can add the next menu item in the same way or by clicking the `+` button (`insert a new array item below`) of another menu item.
2. Expand the [`menu`](/reference/servoyextensions/ui-components/navigation/sidenav.md#menu) property to see the list of menu items. They are also shown in the **Sidenav** 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/sidenav.md#menuitem)
4. Submenu items can be added by clicking the `+` button of the parent menu item and following the same steps.
{% hint style="info" %}
**Sidenav menu items**\
It is necessary to set a unique id in the Sidenav **menu item** [id](/reference/servoyextensions/ui-components/navigation/sidenav.md#menuitem) property.\
Example: `home_page`.
{% endhint %}
## Working with Sidenav
You can find a list of Sidenav **properties** [here](/reference/servoyextensions/ui-components/navigation/sidenav.md#properties).
### Setting the contained form
The initial form to be displayed can be set by selecting a form name in the component's Properties Panel [containedForm](/reference/servoyextensions/ui-components/navigation/sidenav.md#containedform) property.
### Setting header and footer
Sidenav component can include forms acting like headers and footers. This is done by selecting a form name in the component's Properties Panel for the following properties:
* [headerForm](/reference/servoyextensions/ui-components/navigation/sidenav.md#headerform)
* [footerForm](/reference/servoyextensions/ui-components/navigation/sidenav.md#footerform)
### Setting component's menu item's properties
A complete list of component's menu item's properties can be found [here](/reference/servoyextensions/ui-components/navigation/sidenav.md#menuitem).
Important properties to be set:
* `id`: it represents the menu item ID, it is mandatory and must be unique for each menu item
* `text`: displayed text for the menu item
* `enabled`: enables the menu item
* `isDivider`: if this property is set to `true`, then the menu item will be displayed as a visually divider line
* `menuItems`: this property is set exactly as a menu item; here the user can set sub-items for a menu item; each sub-item has the same kind of properties as a main item
* `relationName`: here the user can set an existing relation in case the contained form needs to be loaded through a specific relation
* `formName`: the user can set here the contained form corresponding to each menu item
## Scripting Sidenav
### Main events
You can find a list of Sidenav **events** [here](/reference/servoyextensions/ui-components/navigation/sidenav.md#events).\
You can find a list of Sidenav **API methods** [here](/reference/servoyextensions/ui-components/navigation/sidenav.md#api).
### onMenuItemSelected
This event is called when a menu item is clicked.\
Here is an example of how to use the [onMenuItemSelected](/reference/servoyextensions/ui-components/navigation/sidenav.md#onmenuitemselected) event of Sidenav in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor.md):\
Let's consider the following setup:
* `main_form`: the form where the Sidenav component is placed:
* Sidenav component has the following menu items:
* `id`:`menu_item1`, `text`:`Menu Item #1`
* `id`:`menu_item2`, `text`:`Menu Item #2`
* `id`:`menu_item3`, `text`:`Menu Item #3`
* separate forms showed in `main_form` as a contained form in the Sidenav component: `menu_item1`, `menu_item2`, `menu_item3`.
The following goes on `main_form` script file:
```javascript
/**
* @param menuItemId
* @param {JSEvent} event
*
* @return {Boolean}
*
* @private
*
* @properties={typeid:24,uuid:"D1C19804-0E6A-44C2-B5D4-8934E5B5F5F5"}
*/
function onMenuItemSelected(menuItemId, event) {
elements.sidenav.containedForm = forms[menuItemId]; // menuItemId gets the ID value of the clicked menu item
return false;
}
```
### Setting menu items for a manually configured component's menu
Use the api [**setRootMenuItems**](/reference/servoyextensions/ui-components/navigation/sidenav.md#setrootmenuitems-menuitems) to populate the sidenav with [Menu Items](#menu-item). You can nest Menu Items up to 4 levels depth.
```javascript
var menu = [{
id: 1,
text: "Sample Item #1",
styleClass : "sn-large",
iconStyleClass: "glyphicon glyphicon-search",
data: { description: "This is sample information that can be added to a menuItem" },
menuItems: [{
id: 5,
text: "Sub Item #1"
}, {
id: 6,
text: "Sub Item #2"}]
}, {
id: 2,
text: "Sample Item #2"
},{
isDivider: true
},{
id: 3,
text: "Sample Item #3",
enabled: false
}];
elements.sideNavigation.setRootMenuItems(menu);
```
The method [setRootMenuItems](/reference/servoyextensions/ui-components/navigation/sidenav.md#setrootmenuitems-menuitems) requires an Array of [Menu Item object](/reference/servoycore/dev-api/menus/jsmenuitem.md#overview).
### Menu Item
The menu item is a JSON object representing an item in the sidenav. A menu item may nest other menu items. A menu item may be also used as divider, which is nothing else then a line separating the menu item above and below, in this case all other properties of the menu item are ignored.
Component's Menu Item properties can be found [here](/reference/servoyextensions/ui-components/navigation/sidenav.md#menuitem).\
ServoyMenu's Menu Item properties for Sidenav component can be found [here](/guides/develop/application-design/data-modeling/menu.md#sidenav-properties).
This is a menu item with 2 sub menu items:
**For a manually configured Menu:**
```javascript
var menuItem = {
id: 1,
text: "Sample Item #1",
styleClass : "sn-large",
iconStyleClass: "glyphicon glyphicon-search",
data: { description: "This is sample information that can be added to a menuItem" },
menuItems: [{
id: 5,
text: "Sub Item #1"
}, {
id: 6,
text: "Sub Item #2"}]
};
```
This menu item is instead rendered as a divider:
```javascript
var menuDivider = {
isDivider: true
};
```
***
**For an assigned servoyMenu:**
```javascript
// Get reference to servoyMenu
var menu = elements.sidenav.servoyMenu;
// Create a new menu item
var newItem = menu.addMenuItem("item1");
newItem.menuText = "Sample Item #1";
newItem.iconStyleClass = "glyphicon glyphicon-search";
// Add sub-menu items
var subItem1 = newItem.addMenuItem("sub_item1");
subItem1.menuText = "Sub Item #1";
var subItem2 = newItem.addMenuItem("sub_item2");
subItem2.menuText = "Sub Item #2";
```
### Add a Menu Item
Add a menu item. The menu is added as sub Menu Item if a `menuItemId` is provided, otherwise is added in root. If index is provided the menu is added at the specified index position, otherwise is added as last element. Return false if `menuItemId` cannot be found.\
Here is an example of how to programmatically add a menu item in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor.md) of the main form, using the the [addMenuItem](/reference/servoyextensions/ui-components/navigation/sidenav.md#addmenuitem):
**For a manually configured Menu:**
```javascript
var menuItem = {
id: 100,
text: "Sample Item #1",
styleClass : "nav-large nav-primary",
iconStyleClass: "glyphicon glyphicon-search",
data: { description: "This is sample information that can be added to a menuItem" },
menuItems: [{
id: 101,
text: "Sub Item #1"
}, {
id: 102,
text: "Sub Item #2"}]
};
elements.sideNavigation.addMenuItem(menuItem, 1, 0); // parameters are : menuItem, menuItemId, index
```
***
**For an assigned servoyMenu:**
```javascript
// Get reference to servoyMenu
var menu = elements.sidenav.servoyMenu;
// Create a new menu item
var newItem = menu.addMenuItem("item1");
newItem.menuText = "Sample Item #1";
newItem.iconStyleClass = "glyphicon glyphicon-search";
```
### Setting sub-menu items
Set the `menuItems` as sub-menu items of the menu item with id `menuItemId`. This function returns `false` if `menuItemId` cannot be found.\
Here is an example of how to programmatically set sub-menu items in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor.md) of the main form, using the the [setSubMenuItems](/reference/servoyextensions/ui-components/navigation/sidenav.md#setsubmenuitems):
**For a manually configured Menu:**
```javascript
var menuItems = [{
id: 10,
text: "Sample Item #1",
styleClass : "sn-large",
iconStyleClass: "glyphicon glyphicon-search",
data: { description: "This is sample information that can be added to a menuItem" },
menuItems: [{
id: 12,
text: "Sub Item #1"
}
}]
}, {
id: 11,
text: "Sample Item #2"
},{
isDivider: true
}];
elements.sideNavigation.setSubMenuItems(menuItems);
```
***
**For an assigned servoyMenu:**
```javascript
// get reference to the desired menu item
var menuItem = elements.sidenav.servoyMenu.getMenuItem("item1");
// Add sub-menu items
var subItem1 = menuItem.addMenuItem("sub_item1");
subItem1.menuText = "Sub Item #1";
var subItem2 = menuItem.addMenuItem("sub_item2");
subItem2.menuText = "Sub Item #2";
```
### Update a Menu Item
To update a menu item you should get the menu item object using the component's API [getMenuItem](/reference/servoyextensions/ui-components/navigation/sidenav.md#getmenuitem), any change to the returned object will be reflected on the sidenav component.
Example\
**For a manually configured Menu:**
```javascript
var menuItem = elements.sidenav.getMenuItem(1);
menuItem.text = "Update the text of the menuItem";
menuItem.styleClass = "nav-large nav-bold";
menuItem.data = { "lastUpdate" : new Date(); }
```
Updating an old reference of the menuItem which has not been retrieved via API it won't be possible.
Don't do this:
```javascript
var menuItem = { id:1, text: "init text"};
elements.sidenav.addMenuItem(menuItem);
menuItem.text = "Update text of menu item 1 like this is not reflected on UI"
```
**Instead do**:
```javascript
var menuItem = { id:1, text: "init text"};
elements.sidenav.addMenuItem(menuItem);
// get the menuItem via API
menuItem = elements.sidenav.getMenuItem(1);
menuItem.text = "Update text of menu item 1 like this is correct"
```
***
**For an assigned servoyMenu:**
```javascript
// get the menuItem via API
var menuItem = elements.sidenav.servoyMenu.getMenuItem("item1");
//update the menu item as needed
menuItem.menuText = "Update the text of the menuItem";
menuItem.styleClass = "nav-large nav-bold";
```
### Remove all menu items
If a depth value is specified, all menu items at that depth will be removed. If the depth is set to `1`, all root menu items will be removed. The default depth is `1`.\
Here is an example of how to programmatically remove all menu items in the [Scripting Editor](/reference/servoy-developer/object-editors/scripting-editor.md) of the main form, using the the [clearMenuItems](/reference/servoyextensions/ui-components/navigation/sidenav.md#clearmenuitems):
```javascript
// clear the whole menu removing all nodes.
elements.sidenav.clearMenuItems();
// clear menu at depth 2 removes the sub menu items of each root menu.
elements.sidenav.clearMenuItems(2);
```
---
# 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/sidenav.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.