ShellBar

<ui5-shellbar> | Since 0.8.0

The ui5-shellbar is meant to serve as an application header and includes numerous built-in features, such as: logo, profile image/icon, title, search field, notifications and so on.

Stable DOM Refs

You can use the following stable DOM refs for the ui5-shellbar:

logo
notifications
overflow
profile
product-switch

Keyboard Handling

This component provides a build in fast navigation group which can be used via [F6] / [Shift] + [F6] / [Ctrl] + [Alt/Option] / [Down] or [Ctrl] + [Alt/Option] + [Up]. In order to use this functionality, you need to import the following module: import "@ui5/webcomponents-base/dist/features/F6Navigation.js"

ES6 Module Import

import "@ui5/webcomponents-fiori/dist/ShellBar.js";

Basic Sample

The ShellBar includes Back button, Logo, Title and Profile image.

Properties

hideSearchButton

Description	Defines the visibility state of the search button. Note: The `hideSearchButton` property is in an experimental state and is a subject to change.
Type	`boolean`
Default	false

disableAutoSearchField

Description	Disables the automatic search field expansion/collapse when the available space is not enough. Note: The `disableAutoSearchField` property is in an experimental state and is a subject to change.
Type	`boolean`
Default	false

primaryTitle

Description	Defines the `primaryTitle`. Note: The `primaryTitle` would be hidden on S screen size (less than approx. 700px).
Type	`string \| undefined`
Default	undefined

secondaryTitle

Description	Defines the `secondaryTitle`. Note: The `secondaryTitle` would be hidden on S and M screen sizes (less than approx. 1300px).
Type	`string \| undefined`
Default	undefined

notificationsCount

Description	Defines the `notificationsCount`, displayed in the notification icon top-right corner.
Type	`string \| undefined`
Default	undefined

showNotifications

Description	Defines, if the notification icon would be displayed.
Type	`boolean`
Default	false

showProductSwitch

Description	Defines, if the product switch icon would be displayed.
Type	`boolean`
Default	false

accessibilityAttributes

Description	Defines additional accessibility attributes on different areas of the component. The accessibilityAttributes object has the following fields, where each field is an object supporting one or more accessibility attributes: - logo - `logo.role` and `logo.name`. - notifications - `notifications.expanded` and `notifications.hasPopup`. - profile - `profile.expanded`, `profile.hasPopup` and `profile.name`. - product - `product.expanded` and `product.hasPopup`. - search - `search.hasPopup`. - overflow - `overflow.expanded` and `overflow.hasPopup`. - branding - `branding.name`. The accessibility attributes support the following values: - role: Defines the accessible ARIA role of the logo area. Accepts the following string values: `button` or `link`. - expanded: Indicates whether the button, or another grouping element it controls, is currently expanded or collapsed. Accepts the following string values: `true` or `false`. - hasPopup: Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by the button. Accepts the following string values: `dialog`, `grid`, `listbox`, `menu` or `tree`. - name: Defines the accessible ARIA name of the area. Accepts any string.
Type	`ShellBarAccessibilityAttributes`
Default	{}
Since	1.10.0

showSearchField

Description	Defines, if the Search Field would be displayed when there is a valid `searchField` slot. Note: By default the Search Field is not displayed.
Type	`boolean`
Default	false

logoDomRef

Description	Returns the `logo` DOM ref.
Type	`HTMLElement \| null`
Default	null
Readonly	true
Since	1.0.0-rc.16

notificationsDomRef

Description	Returns the `notifications` icon DOM ref.
Type	`HTMLElement \| null`
Default	null
Readonly	true
Since	1.0.0-rc.16

overflowDomRef

Description	Returns the `overflow` icon DOM ref.
Type	`HTMLElement \| null`
Default	null
Readonly	true
Since	1.0.0-rc.16

profileDomRef

Description	Returns the `profile` icon DOM ref.
Type	`HTMLElement \| null`
Default	null
Readonly	true
Since	1.0.0-rc.16

productSwitchDomRef

Description	Returns the `product-switch` icon DOM ref.
Type	`HTMLElement \| null`
Default	null
Readonly	true
Since	1.0.0-rc.16

Slots

assistant

Description	Defines the assistant slot.
Type	`Array<IButton>`
Since	2.0.0

default

Description	Defines the `ui5-shellbar` additional items. Note: You can use the `<ui5-shellbar-item></ui5-shellbar-item>`.
Type	`Array<ShellBarItem>`

profile

Description	You can pass `ui5-avatar` to set the profile image/icon. If no profile slot is set - profile will be excluded from actions. Note: We recommend not using the `size` attribute of `ui5-avatar` because it should have specific size by design in the context of `ui5-shellbar` profile.
Type	`Array<HTMLElement>`
Since	1.0.0-rc.6

logo

Description	Defines the logo of the `ui5-shellbar`. For example, you can use `ui5-avatar` or `img` elements as logo.
Type	`Array<HTMLElement>`
Since	1.0.0-rc.8

menuItems

Description	Defines the items displayed in menu after a click on a start button. Note: You can use the `<ui5-li></ui5-li>` and its ancestors.
Type	`Array<ListItemBase>`
Since	0.10

searchField

Description	Defines the `ui5-input`, that will be used as a search field.
Type	`Array<Input>`

startButton

Description	Defines a `ui5-button` in the bar that will be placed in the beginning. We encourage this slot to be used for a menu button. It gets overstyled to match ShellBar's styling.
Type	`Array<IButton>`

content

Description	Define the items displayed in the content area. Use the `data-hide-order` attribute with numeric value to specify the order of the items to be hidden when the space is not enough. Lower values will be hidden first. Note: The `content` slot is in an experimental state and is a subject to change.
Type	`Array<UI5Element>`
Since	2.7.0

Events

notifications-click

Description	Fired, when the notification icon is activated.
Type	`CustomEvent<ShellBarNotificationsClickEventDetail>`
Parameters	targetRef: `HTMLElement` dom ref of the activated element
Bubbles	Yes
Cancelable	Yes - via `preventDefault()`

profile-click

Description	Fired, when the profile slot is present.
Type	`CustomEvent<ShellBarProfileClickEventDetail>`
Parameters	targetRef: `HTMLElement` dom ref of the activated element
Bubbles	Yes
Cancelable	No

product-switch-click

Description	Fired, when the product switch icon is activated. Note: You can prevent closing of overflow popover by calling `event.preventDefault()`.
Type	`CustomEvent<ShellBarProductSwitchClickEventDetail>`
Parameters	targetRef: `HTMLElement` dom ref of the activated element
Bubbles	Yes
Cancelable	Yes - via `preventDefault()`

logo-click

Description	Fired, when the logo is activated.
Type	`CustomEvent<ShellBarLogoClickEventDetail>`
Parameters	targetRef: `HTMLElement` dom ref of the activated element
Since	0.10
Bubbles	Yes
Cancelable	No

Description	Fired, when a menu item is activated Note: You can prevent closing of overflow popover by calling `event.preventDefault()`.
Type	`CustomEvent<ShellBarMenuItemClickEventDetail>`
Parameters	item: `HTMLElement` DOM ref of the activated list item
Since	0.10
Bubbles	Yes
Cancelable	Yes - via `preventDefault()`

search-button-click

Description	Fired, when the search button is activated. Note: You can prevent expanding/collapsing of the search field by calling `event.preventDefault()`.
Type	`CustomEvent<ShellBarSearchButtonEventDetail>`
Parameters	targetRef: `HTMLElement` dom ref of the activated element searchFieldVisible: `Boolean` whether the search field is visible
Bubbles	Yes
Cancelable	Yes - via `preventDefault()`

search-field-toggle

Description	Fired, when the search field is expanded or collapsed.
Type	`CustomEvent<ShellBarSearchFieldToggleEventDetail>`
Parameters	expanded: `Boolean` whether the search field is expanded
Since	2.10.0
Bubbles	Yes
Cancelable	No

content-item-visibility-change

Description	Fired, when an item from the content slot is hidden or shown. Note: The `content-item-visibility-change` event is in an experimental state and is a subject to change.
Type	`CustomEvent<ShellBarContentItemVisibilityChangeEventDetail>`
Parameters	array: `Array<HTMLElement>` of all the items that are hidden
Since	2.7.0
Bubbles	Yes
Cancelable	No

Methods

closeOverflow

Description	Closes the overflow area. Useful to manually close the overflow after having suppressed automatic closing with preventDefault() of ShellbarItem's press event
Return type	`void`

getSearchButtonDomRef

Description	Returns the `search` icon DOM ref.
Return type	`Promise<HTMLElement \| null>`
Since	2.10.0

CSS Parts

Name	Description
root	Used to style the outermost wrapper of the `ui5-shellbar`

More Samples

Profile Area

Press the profile image on the right-most side to open a simple popup that one can implment its own profile area.

Stable DOM Refs​

Keyboard Handling​

Fast Navigation​

ES6 Module Import​

Basic Sample​

Properties​

hideSearchButton​

disableAutoSearchField​

primaryTitle​

secondaryTitle​

notificationsCount​

showNotifications​

showProductSwitch​

accessibilityAttributes​

showSearchField​

logoDomRef​

notificationsDomRef​

overflowDomRef​

profileDomRef​

productSwitchDomRef​

Slots​

assistant​

default​

profile​

logo​

menuItems​

searchField​

startButton​

content​

Events​

notifications-click​

profile-click​

product-switch-click​

logo-click​

menu-item-click​

search-button-click​

search-field-toggle​

content-item-visibility-change​

Methods​

closeOverflow​

getSearchButtonDomRef​

CSS Parts​

More Samples​

Profile Area​