# sidebar This UI component displays a sidebar with items on the left side of the screen on desktop and tablets, to indicate to the user how far they are progressing with a process. {% hint style="info" %} **Sidebar hidden by default on small screens** By default the sidebar is not shown if the app is used on devices with smaller screens (< 768px). This behavior can be changed in its configuration. {% endhint %} The text contained inside the `` tag can be a [formatted string](https://docs.journeyapps.com/reference/app-features/xml-format-strings), meaning that you can make the text dynamic. ```xml Pending Dispatched Arrived Work Started Closed ``` {% hint style="info" %} **Sidebar Priority** The sidebar must be the first component listed in the View XML. {% endhint %} ![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-bdee82675d09a5d6d2db89005a18905518ab0b6e%2Fsidebar-overview.png?alt=media) ### Configuration #### sidebar | Option | Required | Details | | ------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `position` | *optional* |

Specifies the position of the sidebar. Can be left or right.
Can also be specified by returning a value from a function.
Defaults to left.
Note that the position of the sidebar will only update after a view transition.

| | `items` | *optional* |

Function which returns an array of component.sidebarItem objects.
Note: If items= is specified, the sidebar cannot contain any \ children.

| | `visible-on-mobile` | *optional* |

Boolean indicating whether or not to show the sidebar on mobile.
Can be either "true" or "false".
Defaults to "false"

| #### item | Option | Required | Details | | --------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `state` | *optional* |

The way the sidebar item is visually rendered, to indicate to the user whether they have already completed the step indicated by the sidebar item in a process. It can be one of the following:

In other words, exactly one field should be active. All fields before it should be normal, and all fields afterwards should be disabled.
Defaults to normal

| | `icon` | *optional* | Path of the icon to display on the sidebar item, left of the text. Icons can be uploaded using the **Assets** workspace in OXIDE. | | `icon-color` | *optional* |

Sets the icon's color. Can be a named color, like primary or a hex value, like #008000.
Can also be specified by returning a value from a function.
Return null to use the icon's default color.
Was added in version 4.36.0 of the JourneyApps Container.

| | `show-if` | *optional* | Controls whether the sidebar item is hidden or shown. The argument specified to `show-if` can either be a literal boolean value (`true` or `false`), or it can specify a variable, parameter or field that can be a string, number, object, etc. that **evaluates to false** or **evaluates to true** (see the reference documentation for [`show-if`](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/show-if) and [`hide-if`](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/hide-if) for further details) | | `hide-if` | *optional* | The opposite of `show-if` (see above). | | `on-press` | *optional* |

Function to call when the item is pressed - either a JavaScript/TypeScript function or a navigation function.
Note: Adding on-press to an item adds a right chevron icon to its right-hand-side.

| | `on-press-icon` | *optional* |

The Ionicon to display on the right-hand-side of the item, typically denoting the action.
Defaults to ion-chevron-right

| | `validate` | *optional* | Whether to run field validation before calling the associated `on-press` (see above). Can be either `true`, `false`, or the result of a function, e.g. (`$:shouldBeValidated()`). | ### Dynamically Generated Sidebars {% hint style="info" %} **Version compatibility** The feature to generate sidebars dynamically was introduced in version **4.38.5** of the JourneyApps Container. {% endhint %} ```xml ``` The function in `items=` must return an array of `component.sidebarItem` objects. `component.sidebarItem` has the following properties: ```javascript { label: string; state: string; icon: string; iconColor: string; onPress: function; onPressIcon: string; validate: boolean; } ``` {% hint style="info" %} **Implicit `show-if` and `hide-if`** Note that the items specified above do not have `showIf` or `hideIf` fields. All items added to the array will automatically be shown. In order to hide an item, omit it from the returned array. {% endhint %} ### Basic Example ```xml ``` ```javascript function getItems() { var items = []; items.push( component.sidebarItem({ label: 'Home', onPress: function() { link.home(); } }) ); items.push( component.sidebarItem({ label: 'Orders', state: 'active' }) ); // You can also construct a sidebarItem like this: var thirdItem = component.sidebarItem(); thirdItem.label = 'Staff'; thirdItem.onPress = function() { link.staff(); }; thirdItem.icon = 'fa-user-astronaut'; items.push(thirdItem); return items; } ``` ### Example 1 using SharedJS ```xml ``` ```javascript // In your app's SharedJS function getSharedItems() { return [ component.sidebarItem({ label: 'Item 1' }), component.sidebarItem({ label: 'Item 2' }) ]; } ``` ### Example 2 using SharedJS ```xml ``` ```javascript // In your app's SharedJS function getItemsInSharedJS() { return [ component.sidebarItem({ label: 'Item 1' }), component.sidebarItem({ label: 'Item 2' }) ]; } // In your view's JS function getItems() { return getItemsInSharedJS().concat([ component.sidebarItem({ label: 'Item 3' }) ]); } ```