# sidenav

(part of package '[Servoy Extra Components](/reference/servoyextensions/packages/ui-component-packages/servoy-extra-components.md)')\
Extends designtime/SolutionModel: [JSWebComponent](/reference/servoycore/dev-api/solutionmodel/jswebcomponent.md)\
Extends runtime: [RuntimeWebComponent](/reference/servoycore/dev-api/forms/runtimeform/elements/runtimewebcomponent.md)

A component that provides a side navigation menu.

This is a reference page; many components have detailed usage guides [here](https://docs.servoy.com/guides/develop/application-design/ui-components).

## Properties

### animate

Flag indicating whether animations are enabled. Type: [Boolean](/reference/servoycore/dev-api/js-lib/boolean.md) Default Value: true

***

### containedForm

The form displayed within the sidenav. Type: [Form](/reference/servoy-developer/component_and_service_property_types.md#form)

***

### enabled

Flag indicating whether the sidenav is enabled for user interaction. Type: [Enabled](/reference/servoy-developer/component_and_service_property_types.md#protected) Default Value: true

***

### footerForm

The footer form of the sidenav. Type: [Form](/reference/servoy-developer/component_and_service_property_types.md#form)

***

### footerFormStickyBottom

Flag indicating whether the footerForm remains fixed at the bottom in CSS Potion forms. Type: [Boolean](/reference/servoycore/dev-api/js-lib/boolean.md) Default Value: false

***

### headerForm

The header form of the sidenav. Type: [Form](/reference/servoy-developer/component_and_service_property_types.md#form)

***

### iconCloseStyleClass

CSS style classes for the icon when the sidenav is closed. Type: [Styleclass](/reference/servoy-developer/component_and_service_property_types.md#styleclass) Default Value: "fa fa-bars"

***

### iconCollapseStyleClass

CSS style classes for the icon used to collapse a menu item. Type: [Styleclass](/reference/servoy-developer/component_and_service_property_types.md#styleclass) Default Value: "fa fa-caret-down"

***

### iconExpandStyleClass

CSS style classes for the icon used to expand a menu item. Type: [Styleclass](/reference/servoy-developer/component_and_service_property_types.md#styleclass) Default Value: "fa fa-caret-right"

***

### iconOpenStyleClass

CSS style classes for the icon when the sidenav is open. Type: [Styleclass](/reference/servoy-developer/component_and_service_property_types.md#styleclass) Default Value: "fa fa-bars"

***

### location

The position of the sidenav on the form. Type: [Point](https://github.com/Servoy/gitbook/blob/master/reference/servoycore/dev-api/js-lib/point.md)

***

### menu

The root menu items for the sidenav. Type: [Array\<CustomType\<servoyextra-sidenav.MenuItem>>](#menuitem) Default Value: \[]

***

### open

Flag indicating whether the sidenav is open. Type: [Boolean](/reference/servoycore/dev-api/js-lib/boolean.md) Default Value: true

***

### relationName

The relation name used to link the contained form to data. Type: [Relation](/reference/servoy-developer/component_and_service_property_types.md#relation)

***

### responsiveHeight

Height of the container, set only in responsive forms. Type: [Number](/reference/servoycore/dev-api/js-lib/number.md) Default Value: 0

***

### scrollbarPosition

Position of the scrollbar within the sidenav (for example, "left" or "right"). Type: [String](/reference/servoycore/dev-api/js-lib/string.md) Default Value: "left"

***

### servoyMenu

A JSMenu object representing the Servoy menu with extra properties (badgeText, badgeStyleClass, formName, relationName, etc.). Type: [JSMenu](/reference/servoycore/dev-api/menus/jsmenu.md)

***

### sidenavWidth

Width of the container Type: [Number](/reference/servoycore/dev-api/js-lib/number.md) Default Value: "300"

***

### slideAnimation

Animation type for the slide effect (for example, "slide-menu" or "collapse-menu"). Type: [String](/reference/servoycore/dev-api/js-lib/string.md) Default Value: "slide-menu"

***

### slidePosition

Position of the sidenav slide (for example, "left", "right", or "static"). Type: [String](/reference/servoycore/dev-api/js-lib/string.md) Default Value: "left"

***

### styleClass

CSS style classes applied to the sidenav container. Type: [Styleclass](/reference/servoy-developer/component_and_service_property_types.md#styleclass)

***

### tabSeq

Tab sequence order for keyboard navigation. Type: [Tabseq](/reference/servoy-developer/component_and_service_property_types.md#tabseq)

***

### togglePosition

Position of the toggle button (for example, "fixed-toggle", "side-toggle", or "hide-toggle"). Type: [String](/reference/servoycore/dev-api/js-lib/string.md) Default Value: "fixed-toggle"

***

### visible

Flag indicating whether the sidenav is visible. Type: [Visible](/reference/servoy-developer/component_and_service_property_types.md#visible)

***

## Events

### onMenuItemCollapsed(menuItem,event)

Called when a menu item is collapsed.

**Parameters:**

> * {[Object](/reference/servoycore/dev-api/js-lib/object.md)} menuItem The unique identifier of the collapsed menu item.
> * {[JSEvent](/reference/servoycore/dev-api/application/jsevent.md)} event The event object associated with the collapse.

***

### onMenuItemExpanded(menuItem,event)

Called when a menu item is expanded.

**Parameters:**

> * {[Object](/reference/servoycore/dev-api/js-lib/object.md)} menuItem The unique identifier of the expanded menu item.
> * {[JSEvent](/reference/servoycore/dev-api/application/jsevent.md)} event The event object associated with the expansion.

***

### onMenuItemSelected(menuItem,event)

Called when a menu item is selected.

**Parameters:**

> * {[Object](/reference/servoycore/dev-api/js-lib/object.md)} menuItem The unique identifier of the selected menu item.
> * {[JSEvent](/reference/servoycore/dev-api/application/jsevent.md)} event The event object associated with the selection.

**Returns:** {[Boolean](/reference/servoycore/dev-api/js-lib/boolean.md)}

***

### onOpenToggled(event)

Called when the open state of the sidenav is toggled.

**Parameters:**

> * {[JSEvent](/reference/servoycore/dev-api/application/jsevent.md)} event The event object associated with the toggle action.

***

## API

### addMenuItem(menuItem,menuItemId,index)

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.

**@public**\
**Example:**

```js
 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:**

> * {[CustomType\<servoyextra-sidenav.MenuItem>](#menuitem)} menuItem An array containing the menu item(s) to be added. Each menu item should include properties such as \`id\`, \`text\`, \`styleClass\`, \`iconStyleClass\`, \`data\`, and optionally \`menuItems\` for nested sub-menu items.
> * {[Object](/reference/servoycore/dev-api/js-lib/object.md)} \[menuItemId] Add the item as subMenuItem of the menuItemId. Default add the menuItem as root.
> * {[Number](/reference/servoycore/dev-api/js-lib/number.md)} \[index] 0-based. The index at which to insert the item. Index value should not be greater then number of sibelings. Default is at the end.

**Returns:** [Boolean](/reference/servoycore/dev-api/js-lib/boolean.md) Returns \`false\` if the \`menuItemId\` cannot be found, otherwise \`true\` indicating the menu item was successfully added.

***

### clearMenuItems(depth)

Remove all the menu items. If depth is specified removes all the menu items at depth.\
If depth is equal to 1 all roots will be removed. Default depth is 1.

**@public**\
**Example:**

```js
// 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);
```

**Parameters:**

> * {[Number](/reference/servoycore/dev-api/js-lib/number.md)} \[depth] 1-based. Default 1.

***

### getLocation(menuItemId)

Retrieves the screen location of a specific menu item. Returns the location as point (object with x and y properties).

**Parameters:**

> * {[Object](/reference/servoycore/dev-api/js-lib/object.md)} menuItemId The node to retrieve location for.

**Returns:** [Point](https://github.com/Servoy/gitbook/blob/master/reference/servoycore/dev-api/js-lib/point.md) The location of the menu item.

***

### getMenuItem(menuItemId)

Returns the menuItem object

**@public**

**Parameters:**

> * {[Object](/reference/servoycore/dev-api/js-lib/object.md)} menuItemId The unique identifier of the menu item to retrieve.

**Returns:** [CustomType\<servoyextra-sidenav.MenuItem>](#menuitem) The menu item object corresponding to the specified \`menuItemId\`.

***

### getParentMenuItem(menuItemId)

Returns the parent menuItem object of the menu item with id menuItemId

**@public**

**Parameters:**

> * {[Object](/reference/servoycore/dev-api/js-lib/object.md)} menuItemId The unique identifier of the menu item whose parent menu item is to be retrieved.

**Returns:** [CustomType\<servoyextra-sidenav.MenuItem>](#menuitem) The parent menu item object of the specified \`menuItemId\`.

***

### getRootMenuItems()

Returns the root menu object

**@public**

**Returns:** [Array\<CustomType\<servoyextra-sidenav.MenuItem>>](#menuitem) An array of root menu item objects representing the top-level menu structure of the sidenav.

***

### getSelectedMenuItem(level)

Returns the selected menuItem.

**@public**

**Parameters:**

> * {[Number](/reference/servoycore/dev-api/js-lib/number.md)} \[level] If level is provided search for the selected menu item at level.

**Returns:** [CustomType\<servoyextra-sidenav.MenuItem>](#menuitem) The selected menu item object.

***

### getSize(menuItemId)

Retrieves the size of a specific menu item. Returns the size as dimension (object with width and height properties).

**Parameters:**

> * {[Object](/reference/servoycore/dev-api/js-lib/object.md)} menuItemId The id to retrieve size for.

**Returns:** [Dimension](https://github.com/Servoy/gitbook/blob/master/reference/servoycore/dev-api/js-lib/dimension.md) The size of the menu item.

***

### getSubMenuItems(menuItemId)

Returns the sub menu items of the menu item with id 'menuItemId'

**@public**

**Parameters:**

> * {[Object](/reference/servoycore/dev-api/js-lib/object.md)} menuItemId The unique identifier of the menu item whose sub-menu items are to be retrieved.

**Returns:** [Array\<CustomType\<servoyextra-sidenav.MenuItem>>](#menuitem) An array of sub-menu items for the specified menu item.

***

### isMenuItemEnabled(menuItemId)

Returns true if the menuItem and all it's ancestors are enabled.\
Return false if menuItemId cannot be found. \*NOTE: The method returns false if any ancestor of the menuItem is not enabled; if the property enabled of the menuItem is set to true, but has a parent with the enabled property set to false, then isMenuItemEnabled returns false. \*

**@public**

**Parameters:**

> * {[Object](/reference/servoycore/dev-api/js-lib/object.md)} menuItemId The unique identifier of the menu item to check.

**Returns:** [Boolean](/reference/servoycore/dev-api/js-lib/boolean.md) Returns \`true\` if the specified menu item and all its ancestors are enabled. Returns \`false\` if the \`menuItemId\` cannot be found or if any ancestor of the menu item is not enabled.

***

### isMenuItemExpanded(menuItemId)

Returns true if the menuItem is expanded.

**@public**

**Parameters:**

> * {[Object](/reference/servoycore/dev-api/js-lib/object.md)} menuItemId The unique identifier of the menu item to check.

**Returns:** [Boolean](/reference/servoycore/dev-api/js-lib/boolean.md) Returns \`true\` if the specified menu item is currently expanded, otherwise \`false\`.

***

### removeMenuItem(menuItemId)

Remove the menu item and all it's subMenuItems from the tree.\
Return false if menuItemId cannot be found.

**@public**

**Parameters:**

> * {[Object](/reference/servoycore/dev-api/js-lib/object.md)} menuItemId The unique identifier of the menu item to be removed, including all its sub-menu items.

**Returns:** [Boolean](/reference/servoycore/dev-api/js-lib/boolean.md) True if the menu item was successfully removed; false if the specified menuItemId could not be found.

***

### removeSubMenuItems(menuItemId)

Remove all the sub menu items of the menu item with id 'menuItemId' Return false if menuItemId cannot be found.

**@public**

**Parameters:**

> * {[Object](/reference/servoycore/dev-api/js-lib/object.md)} menuItemId The unique identifier of the menu item whose sub-menu items are to be removed.

**Returns:** [Boolean](/reference/servoycore/dev-api/js-lib/boolean.md) True if the sub-menu items were successfully set; false if the specified menuItemId could not be found.

***

### setMenuItemEnabled(menuItemId,enabled)

Enable or disable the menuItem Return false if menuItemId cannot be found.

**@public**

**Parameters:**

> * {[Object](/reference/servoycore/dev-api/js-lib/object.md)} menuItemId The unique identifier of the menu item to enable or disable.
> * {[Boolean](/reference/servoycore/dev-api/js-lib/boolean.md)} enabled A boolean value where \`true\` enables the menu item and \`false\` disables it.

**Returns:** [Boolean](/reference/servoycore/dev-api/js-lib/boolean.md) Returns \`false\` if the \`menuItemId\` cannot be found, otherwise \`true\` indicating the operation was successful.

***

### setMenuItemExpanded(menuItemId,expanded,mustExecuteOnMenuItemExpand)

Force the menuItem to be expanded or collapsed.\
Return false if menuItemId cannot be found or is disabled.

**@public**

**Parameters:**

> * {[Object](/reference/servoycore/dev-api/js-lib/object.md)} menuItemId The unique identifier of the menu item to expand or collapse.
> * {[Boolean](/reference/servoycore/dev-api/js-lib/boolean.md)} expanded Force the menuItem to expand if true, is collapsed otherwise
> * {[Boolean](/reference/servoycore/dev-api/js-lib/boolean.md)} \[mustExecuteOnMenuItemExpand] Force the onMenuItemExpand to be executed. Default false.

**Returns:** [Boolean](/reference/servoycore/dev-api/js-lib/boolean.md) Returns \`false\` if the \`menuItemId\` cannot be found or is disabled, otherwise \`true\` indicating the operation was successful.

***

### setRootMenuItems(menuItems)

Init the menu setting the root menuItems.

**@public**\
**Example:**

```js
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);
```

**Parameters:**

> * {[Array\<CustomType\<servoyextra-sidenav.MenuItem>>](#menuitem)} menuItems Is an array of MenuItem objects. A MenuItem type is like this {{id: String|Number, text: String=, styleClass: String=, iconStyleClass: String=, enabled: Boolean=, data: Object=, menuItems: Array=, isDivider : Boolean=}} Each MenuItem object should set the required properties 'id', which uniquely identifies the menuItem object in menu, and 'text' property. The MenuItem may contain the optional properties 'styleClass', 'iconStyleClass', 'data', 'enabled', 'menuItems', 'isDivider'

***

### setSelectedMenuItem(menuItemId,mustExecuteOnMenuItemSelected,mustExecuteOnMenuItemExpand,level)

Select the menu item with the given id.\
If level is provided search is optimized since it will search only within the descendant of the selected menuItem at level.\
For example if a root menuItem is selected and level is equal 2 search only in the subMenuItems of the selected root.\
Return false if menuItemId cannot be found or is disabled.

**@public**

**Parameters:**

> * {[Object](/reference/servoycore/dev-api/js-lib/object.md)} menuItemId The unique identifier of the menu item to select.
> * {[Boolean](/reference/servoycore/dev-api/js-lib/boolean.md)} \[mustExecuteOnMenuItemSelected] Force the onMenuItemSelect to be executed. Default false.
> * {[Boolean](/reference/servoycore/dev-api/js-lib/boolean.md)} \[mustExecuteOnMenuItemExpand] Force the onMenuItemExpand to be executed. Default false.
> * {[Number](/reference/servoycore/dev-api/js-lib/number.md)} \[level] Reduce the search to the selected menuItem at level, if any menuItem is selected at level.

**Returns:** [Boolean](/reference/servoycore/dev-api/js-lib/boolean.md) Returns \`true\` if the menu item is successfully selected, otherwise \`false\` if the \`id\` cannot be found or the menu item is disabled.

***

### setSelectedMenuItemAsync(menuItemId)

**@deprecated** use setSelectedMenuItem(id, false, false) instead.

Select the menu item with the given id.

This function doesn't wait for a return value;\
use setSelectedMenuItem if you want to know if the menu item can be select successfully\
\&#xNAN;**@public**

**Parameters:**

> * {[Object](/reference/servoycore/dev-api/js-lib/object.md)} menuItemId

***

### setSubMenuItems(menuItemId,menuItems)

Set the menuItems as sub menu items of the menu item with id 'menuItemId' Return false if menuItemId cannot be found.

**@public**\
**Example:**

```js
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);
```

**Parameters:**

> * {[Object](/reference/servoycore/dev-api/js-lib/object.md)} menuItemId The unique identifier of the menu item to which the provided sub-menu items should be added.
> * {[Array\<CustomType\<servoyextra-sidenav.MenuItem>>](#menuitem)} menuItems String|Number, text: String=, styleClass: String=, iconStyleClass: String=, enabled: Boolean=, data: Object=, menuItems: Array=, isDivider : Boolean=}>} menuItems is an array of MenuItem objects. Each MenuItem object should set the required properties 'id', which uniquely identifies the menuItem object in menu, and 'text' property. The MenuItem may contain the optional properties 'styleClass', 'iconStyleClass', 'data', 'enabled', 'menuItems', 'isDivider'.

**Returns:** [Boolean](/reference/servoycore/dev-api/js-lib/boolean.md) Returns \`false\` if the \`menuItemId\` cannot be found, otherwise \`true\` indicating the sub-menu items were successfully set.

***

## Types

## MenuItem

Represents a menu item in the sidenav. scripting type: CustomType\<servoyextra-sidenav.MenuItem>

* badgeStyleClass
  * CSS style classes applied to the badge.
  * **Type**: [styleclass](/reference/servoy-developer/component_and_service_property_types.md#styleclass)
  * **Default Value**: "badge text-bg-secondary"
* badgeText
  * Badge text displayed with the menu item.
  * **Type**: [tagstring](/reference/servoy-developer/component_and_service_property_types.md#tagstring)
* data
  * Custom data associated with the menu item.
  * **Type**: [object](/reference/servoycore/dev-api/js-lib/object.md)
* enabled
  * Flag indicating whether the menu item is enabled.
  * **Type**: [boolean](/reference/servoycore/dev-api/js-lib/boolean.md)
  * **Default Value**: true
* formName
  * The name of the form to be opened when the menu item is selected.
  * **Type**: [form](/reference/servoy-developer/component_and_service_property_types.md#form)
* iconStyleClass
  * CSS style classes applied to the menu item's icon.
  * **Type**: [styleclass](/reference/servoy-developer/component_and_service_property_types.md#styleclass)
* id
  * Unique identifier of the menu item.
  * **Type**: [object](/reference/servoycore/dev-api/js-lib/object.md)
* isDivider
  * Flag indicating whether the menu item is a divider.
  * **Type**: [boolean](/reference/servoycore/dev-api/js-lib/boolean.md)
  * **Default Value**: false
* menuItems
  * An array of child menu items (sub-menu items).
  * **Type**: [MenuItem\[\]](#menuitem)
* relationName
  * The relation name used to link to the form.
  * **Type**: [relation](/reference/servoy-developer/component_and_service_property_types.md#relation)
* styleClass
  * CSS style classes applied to the menu item.
  * **Type**: [styleclass](/reference/servoy-developer/component_and_service_property_types.md#styleclass)
* text
  * The text label of the menu item.
  * **Type**: [tagstring](/reference/servoy-developer/component_and_service_property_types.md#tagstring)
* tooltip
  * Tooltip text for the menu item.
  * **Type**: [tagstring](/reference/servoy-developer/component_and_service_property_types.md#tagstring)

***


---

# 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/reference/servoyextensions/ui-components/navigation/sidenav.md?ask=<question>
```

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.