Vaadin WC API reference

MenuBar

View as MD

Description

<vaadin-menu-bar> is a Web Component providing a set of horizontally stacked buttons offering the user quick access to a consistent set of commands. Each button can toggle a submenu with support for additional levels of nested menus.

To create the menu bar, first add the component to the page:

<vaadin-menu-bar></vaadin-menu-bar>

And then use items property to initialize the structure:

document.querySelector('vaadin-menu-bar').items = [{text: 'File'}, {text: 'Edit'}];

Styling

The following shadow DOM parts are exposed for styling:

Part name Description
container The container wrapping menu bar buttons.

The following state attributes are available for styling:

Attribute Description
disabled Set when the menu bar is disabled
has-single-button Set when there is only one button visible

See Styling Components documentation.

Internal components

In addition to <vaadin-menu-bar> itself, the following internal components are themable:

The <vaadin-menu-bar-item> sub-menu elements have the following additional state attributes on top of the built-in <vaadin-item> state attributes:

Attribute Description
expanded Expanded parent item.

Properties

disabled

Type: boolean

If true, the user cannot interact with this element.

i18n

Type: MenuBarI18n

The object used to localize this component. To change the default localization, replace this with an object that provides all properties, or just the individual properties you want to change.

The object has the following JSON structure and default values:

{
  moreOptions: 'More options'
}

See also: MenuBarI18n

items

Type: MenuBarItem[]

Defines a hierarchical structure, where root level items represent menu bar buttons, and children property configures a submenu with items to be opened below the button on click, Enter, Space, Up and Down arrow keys.

Example 

menubar.items = [
  {
    text: 'File',
    className: 'file',
    children: [
      {text: 'Open', className: 'file open'}
      {text: 'Auto Save', checked: true},
    ]
  },
  {component: 'hr'},
  {
    text: 'Edit',
    children: [
      {text: 'Undo', disabled: true},
      {text: 'Redo'}
    ]
  },
  {text: 'Help'}
];

Disabled buttons

When disabled, menu bar buttons (root-level items) are rendered as "dimmed" and prevent all user interactions (mouse and keyboard).

Since disabled buttons are not focusable and cannot react to hover events by default, it can cause accessibility issues by making them entirely invisible to assistive technologies, and prevents the use of Tooltips to explain why the action is not available. This can be addressed by enabling the feature flag accessibleDisabledButtons, which makes disabled buttons focusable and hoverable, while still preventing them from being triggered:

// Set before any menu bar is attached to the DOM.
window.Vaadin.featureFlags.accessibleDisabledButtons = true;

// Set before any menu bar is attached to the DOM.
window.Vaadin.featureFlags.accessibleDisabledButtons = true;

See also: MenuBarItem

openOnHover

Type: boolean | null | undefined

If true, the submenu will open on hover (mouseover) instead of click.

reverseCollapse

Type: boolean | null | undefined

If true, the buttons will be collapsed into the overflow menu starting from the "start" end of the bar instead of the "end".

tabNavigation

Type: boolean | null | undefined

If true, the top-level menu items is traversable by tab instead of arrow keys (i.e. disabling roving tabindex)

Methods

close

Type: () => void

Closes the current submenu.

Events

item-selected

Type: MenuBarItemSelectedEvent

Fired when either a submenu item or menu bar button without nested children is clicked.

Types 

export interface MenuBarI18n {
  moreOptions?: string;
}
export type MenuBarItem<TItemData extends object = object> = {
  /**
   * Text to be set as the menu button component's textContent.
   */
  text?: string;
  /**
   * Text to be set as the menu button's tooltip.
   * Requires a `<vaadin-tooltip slot="tooltip">` element to be added inside the `<vaadin-menu-bar>`.
   */
  tooltip?: string;
  /**
   * The component to represent the button content.
   * Either a tagName or an element instance. Defaults to "vaadin-menu-bar-item".
   */
  component?: HTMLElement | string;
  /**
   * If true, the button is disabled and cannot be activated.
   */
  disabled?: boolean;
  /**
   * Theme(s) to be set as the theme attribute of the button, overriding any theme set on the menu bar.
   */
  theme?: string[] | string;
  /**
   * Array of submenu items.
   */
  children?: Array<SubMenuItem<TItemData>>;

  /**
   * Class/classes to be set to the class attribute of the button.
   */
  className?: string;
} & TItemData;
/**
 * Fired when a submenu item or menu bar button without children is clicked.
 */
export type MenuBarItemSelectedEvent<TItem extends MenuBarItem = MenuBarItem> = CustomEvent<{ value: TItem }>;
export type SubMenuItem<TItemData extends object = object> = {
  text?: string;
  component?: HTMLElement | string;
  disabled?: boolean;
  theme?: string[] | string;
  checked?: boolean;
  className?: string;
  children?: Array<SubMenuItem<TItemData>>;
} & TItemData;