Menu¶
Contextual menus are lists of commands that are based on the context of a selection, mouse hover or keyboard focus. They are one of the most effective and highly used command surfaces, and can be used in a variety of places.
Usage¶
When to use¶
- If users need to perform several actions on a content
- If the actions are not used on a daily basis
- If there is one action only, use button or link instead
Best practices¶
- Analyze what actions are most important. Order the actions accordingly.
- Group similar actions.
- Move less important actions to a submenu.
- Keep disabled actions visible.
- Do not use more than 2 submenus in a nested way.
- Do not have a long and flat list of actions, which might not have space on a small screen.
Design¶
Elements¶
(1) Hover state, (2) Entry with submenu, (3) Header, (4) Entry menu with icon, (5) Disabled state, (6) Indication for submenu, (7) Divider
Alternatives¶
- Single choice should be used if the user has to select one of the options only. Make sure, that the options are grouped correctly.
- Multi choice can be used, if the user can enable or disable some functionality over the menu.
Code¶
Important API changes
With Element v45, the si-menu has been completely re-implemented to feature a declarative API style based on the CDK Menu. If you are migrating from the old si-menu-legacy, you might want to consider using the si-menu-factory, which provides a more compatible model-driven API.
The si-menu has a declarative API and an additional si-menu-factory which accepts MenuItem[]. It is built around the CDK Menu using Angular's hostDirective feature. Due to this:
CdkMenuTriggeris required to open the menuCdkMenuItemcan be used directly if proper styling is applied (helpful for special use cases)
Usage of the declarative API¶
Usage of the factory API¶
si-menu-bar¶
The si-menu-bar is a horizontal menu that is based on the CdkMenuBar.
While being visually similar to the si-content-action-bar it has two differences:
si-menu-barhas a declarative APIsi-menu-barhas no responsive behavior
In general, we recommend using the si-content-action-bar over the si-menu-bar.
SiMenuItemComponent API Documentation¶
selector
si-menu-item, a[si-menu-item], button[si-menu-item]Input Properties¶
| Name | Type | Default | Description |
|---|---|---|---|
| badge ¶ | (string | number) | ||
| badgeColor ¶ | string | 'secondary' | |
| disabled ¶ | boolean | false | |
| icon ¶ | string | ||
| iconBadgeDot ¶ | (undefined | string | number | boolean) | false |
Output Properties¶
| Name | Type | Description |
|---|---|---|
| (readonly) triggered ¶ | EventEmitter<void> | If this MenuItem is a regular MenuItem, outputs when it is triggered by a keyboard or mouse event. |
SiMenuItemCheckboxComponent API Documentation¶
selector
si-menu-item-checkbox, button[si-menu-item-checkbox]Input Properties¶
| Name | Type | Default | Description |
|---|---|---|---|
| badge ¶ | (string | number) | ||
| badgeColor ¶ | string | 'secondary' | |
| checked ¶ | boolean | Whether the element is checked | |
| disabled ¶ | boolean | false | |
| icon ¶ | string | ||
| iconBadgeDot ¶ | (undefined | string | number | boolean) | false |
Output Properties¶
| Name | Type | Description |
|---|---|---|
| (readonly) triggered ¶ | EventEmitter<void> | If this MenuItem is a regular MenuItem, outputs when it is triggered by a keyboard or mouse event. |
SiMenuItemRadioComponent API Documentation¶
selector
si-menu-item-radioInput Properties¶
| Name | Type | Default | Description |
|---|---|---|---|
| badge ¶ | (string | number) | ||
| badgeColor ¶ | string | 'secondary' | |
| checked ¶ | boolean | Whether the element is checked | |
| disabled ¶ | boolean | false | |
| icon ¶ | string | ||
| iconBadgeDot ¶ | (undefined | string | number | boolean) | false |
Output Properties¶
| Name | Type | Description |
|---|---|---|
| (readonly) triggered ¶ | EventEmitter<void> | If this MenuItem is a regular MenuItem, outputs when it is triggered by a keyboard or mouse event. |
SiMenuFactoryComponent API Documentation¶
selector
si-menu-factoryInput Properties¶
| Name | Type | Default | Description |
|---|---|---|---|
| actionParam ¶ | unknown | ||
| items ¶ | readonly (MenuItem | MenuItem)[] |
CdkMenuTrigger API Documentation¶
A directive that turns its host element into a trigger for a popup menu.
It can be combined with cdkMenuItem to create sub-menus. If the element is in a top level
MenuBar it will open the menu on click, or if a sibling is already opened it will open on hover.
If it is inside of a Menu it will open the attached Submenu on hover regardless of its sibling
state.
Input Properties¶
| Name | Type | Description |
|---|---|---|
| cdkMenuPosition ¶ | ConnectedPosition[] | A list of preferred menu positions to be used when constructing the FlexibleConnectedPositionStrategy for this trigger's menu. |
| cdkMenuTriggerData ¶ | unknown | Context data to be passed along to the menu template |
| cdkMenuTriggerFor ¶ | (null | TemplateRef<unknown>) | Template reference variable to the menu this trigger opens |
Output Properties¶
| Name | Type | Description |
|---|---|---|
| (readonly) cdkMenuClosed ¶ | EventEmitter<void> | Emits when the attached menu is requested to close |
| (readonly) cdkMenuOpened ¶ | EventEmitter<void> | Emits when the attached menu is requested to open |
Attributes and Methods¶
| Name | Type | Description |
|---|---|---|
| close() ¶ | () => void | Close the opened menu. |
| getMenu() ¶ | () => (undefined | Menu) | Get a reference to the rendered Menu if the Menu is open and rendered in the DOM. |
| (readonly) injector ¶ | Injector | The DI injector for this component. |
| isOpen() ¶ | () => boolean | Whether the attached menu is open. |
| open() ¶ | () => void | Open the attached menu. |
CdkContextMenuTrigger API Documentation¶
A directive that opens a menu when a user right-clicks within its host element. It is aware of nested context menus and will trigger only the lowest level non-disabled context menu.
Input Properties¶
| Name | Type | Description |
|---|---|---|
| cdkContextMenuDisabled ¶ | boolean | Whether the context menu is disabled. |
| cdkContextMenuPosition ¶ | ConnectedPosition[] | A list of preferred menu positions to be used when constructing the FlexibleConnectedPositionStrategy for this trigger's menu. |
| cdkContextMenuTriggerData ¶ | unknown | Context data to be passed along to the menu template |
| cdkContextMenuTriggerFor ¶ | (null | TemplateRef<unknown>) | Template reference variable to the menu this trigger opens |
Output Properties¶
| Name | Type | Description |
|---|---|---|
| (readonly) cdkContextMenuClosed ¶ | EventEmitter<void> | Emits when the attached menu is requested to close |
| (readonly) cdkContextMenuOpened ¶ | EventEmitter<void> | Emits when the attached menu is requested to open |
Attributes and Methods¶
| Name | Type | Description |
|---|---|---|
| close() ¶ | () => void | Close the currently opened context menu. |
| (readonly) injector ¶ | Injector | The DI injector for this component. |
| isOpen() ¶ | () => boolean | Whether the attached menu is open. |
Types Documentation¶
|
|
| Represents a menu item that navigates using the Angular Router. Requires a configured Angular Router. | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
|
|
|
|
|
|
| Represents a translatable string. This can either be a translation key, e.g. ACTIONS.EDIT that will be automatically translated when displayed on the UI or a pre-translated string, e.g. Edit . Equivalent to a normal string in usage and functionality. |
|---|
| Implement and provide this to an SiMenuFactoryComponent to receive trigger events. | |||||||
|---|---|---|---|---|---|---|---|
| |||||||
|
Translatable import imported from @siemens/element-translate-ng |
|---|
| Used in events emitted from SiLinkActionService | |||
|---|---|---|---|
|
|
| |||||||
| |||||||
|
Except where otherwise noted, content on this site is licensed under MIT License.