Docs

You are viewing documentation for an older Vaadin version. View latest documentation

Docs

Menu Bar

Menu Bar is a horizontal button bar with hierarchical drop-down menus. Menu items can either trigger an action, open a menu, or work as a toggle.

Open in a
new tab
MenuBar menuBar = new MenuBar();
Text selected = new Text("");
ComponentEventListener<ClickEvent<MenuItem>> listener = e -> selected.setText(e.getSource().getText());
Div message = new Div(new Text("Clicked item: "), selected);

menuBar.addItem("View", listener);
menuBar.addItem("Edit", listener);

MenuItem share = menuBar.addItem("Share");
SubMenu shareSubMenu = share.getSubMenu();
MenuItem onSocialMedia = shareSubMenu.addItem("On social media");
SubMenu socialMediaSubMenu = onSocialMedia.getSubMenu();
socialMediaSubMenu.addItem("Facebook", listener);
socialMediaSubMenu.addItem("Twitter", listener);
socialMediaSubMenu.addItem("Instagram", listener);
shareSubMenu.addItem("By email", listener);
shareSubMenu.addItem("Get Link", listener);

MenuItem move = menuBar.addItem("Move");
SubMenu moveSubMenu = move.getSubMenu();
moveSubMenu.addItem("To folder", listener);
moveSubMenu.addItem("To trash", listener);

menuBar.addItem("Duplicate", listener);

Styles

Default Variants

The following variants are available for adjusting the component’s appearance:

Open in a
new tab
MenuBar menuWithDefaultTheme = new MenuBar();
addItem(menuWithDefaultTheme, "Default");

MenuBar menuWithTertiaryTheme = new MenuBar();
menuWithTertiaryTheme.addThemeVariants(MenuBarVariant.LUMO_TERTIARY);
addItem(menuWithTertiaryTheme, "Tertiary");

MenuBar menuWithPrimaryTheme = new MenuBar();
menuWithPrimaryTheme.addThemeVariants(MenuBarVariant.LUMO_PRIMARY);
addItem(menuWithPrimaryTheme, "Primary");

MenuBar menuWithSmallTheme = new MenuBar();
menuWithSmallTheme.addThemeVariants(MenuBarVariant.LUMO_SMALL);
addItem(menuWithSmallTheme, "Small");
Variant Usage recommendations

Tertiary

Corresponds to the tertiary button variant, omitting the background color.

Primary

Corresponds to the primary button variant. As only one primary action should be presented in the same part of the UI, this should only be used for drop-down button use cases.

Small

Compact variant. Can be combined with Tertiary and Primary.
Tip
Default menu button styles can be customized
Note that the standard Menu Button styles can be adjusted using theme features, so these variants should only be used to differentiate special instances of the component.

Styling Menu Items

An individual menu item can be styled using a custom variant.

To style a root-level item, create a custom variant for the vaadin-menu-bar-button component.

To style a sub-menu item, create a custom variant for the vaadin-context-menu-item component.

See Vaadin Component Variants for details how to add style sheets for those components.

Open in a
new tab
MenuItem view = menuBar.addItem("View");
view.addThemeNames("custom-theme");

MenuItem edit = menuBar.addItem("Edit");

MenuItem share = menuBar.addItem("Share");
SubMenu shareSubMenu = share.getSubMenu();
shareSubMenu.addItem("By email").addThemeNames("custom-theme");
shareSubMenu.addItem("Get Link");

Overflow

Items that don’t fit into the current width of the menu bar automatically collapse into an overflow menu at the end:

Open in a
new tab
MenuBar menuBar = new MenuBar();
addItems(menuBar);
Div div = new Div();
div.setText("Move the splitter to see overflow feature");

SplitLayout splitLayout = new SplitLayout(menuBar, div);

Icons

Menu items can have icons in addition to, or instead of text.

Open in a
new tab
MenuBar menuBar = new MenuBar();
menuBar.addThemeVariants(MenuBarVariant.LUMO_ICON);
MenuItem share = createIconItem(menuBar, VaadinIcon.SHARE, "Share", null);
SubMenu shareSubMenu = share.getSubMenu();
createIconItem(shareSubMenu, VaadinIcon.SHARE, "By Email", null, true);
createIconItem(shareSubMenu, VaadinIcon.LINK, "Get link", null, true);
createIconItem(menuBar, VaadinIcon.COPY, null, "duplicate");

...

private MenuItem createIconItem(HasMenuItems menu, VaadinIcon iconName, String label, String ariaLabel) {
    return createIconItem(menu, iconName, label, ariaLabel, false);
}
private MenuItem createIconItem(HasMenuItems menu, VaadinIcon iconName, String label, String ariaLabel, boolean isChild) {
    Icon icon = new Icon(iconName);

    if (isChild) {
        icon.getStyle().set("width", "var(--lumo-icon-size-s)");
        icon.getStyle().set("height", "var(--lumo-icon-size-s)");
        icon.getStyle().set("marginRight", "var(--lumo-space-s)");
    }

    MenuItem item = menu.addItem(icon, e -> {
    });

    if (ariaLabel != null) {
        item.getElement().setAttribute("aria-label", ariaLabel);
    }

    if (label != null) {
        item.add(new Text(label));
    }

    return item;
}

Usage recommendations:

  • Use icons sparingly. Most actions are difficult to reliably represent with icons, and the benefit of icons in addition to text should be weighed against the additional visual noise this creates.

  • Menu items in dropdown menus should always have text labels.

  • Icon-only menu buttons should be primarily used for extremely common recurring actions with highly standardized, universally understood icons (for example, a cross for close).

  • Icon-only menu buttons should provide a textual alternative for screen readers using the aria-label attribute.

Menu Bars with icon-only top-level items can use the Tertiary Inline style variant to reduce the horizontal padding around the icons.

Open in a
new tab
MenuBar menuBar = new MenuBar();
menuBar.addThemeVariants(MenuBarVariant.LUMO_TERTIARY_INLINE);

createIconItem(menuBar, VaadinIcon.EYE, "View");
createIconItem(menuBar, VaadinIcon.PENCIL, "Edit");

MenuItem share = createIconItem(menuBar, VaadinIcon.SHARE, "Share");
SubMenu shareSubMenu = share.getSubMenu();
MenuItem onSocialMedia = shareSubMenu.addItem("On social media");
SubMenu socialMediaSubMenu = onSocialMedia.getSubMenu();
socialMediaSubMenu.addItem("Facebook");
socialMediaSubMenu.addItem("Twitter");
socialMediaSubMenu.addItem("Instagram");
shareSubMenu.addItem("By email");
shareSubMenu.addItem("Get Link");

MenuItem move = createIconItem(menuBar, VaadinIcon.FOLDER, "Move");
SubMenu moveSubMenu = move.getSubMenu();
moveSubMenu.addItem("To folder");
moveSubMenu.addItem("To trash");

createIconItem(menuBar, VaadinIcon.COPY, "Duplicate");

...

private MenuItem createIconItem(MenuBar menu, VaadinIcon iconName, String ariaLabel) {
    Icon icon = new Icon(iconName);
    MenuItem item = menu.addItem(icon);
    item.getElement().setAttribute("aria-label", ariaLabel);

    return item;
}
Warning
Other components in menu items
While it’s technically possible to put any UI element in a menu item, this can be problematic in terms of accessibility, as they cannot be focused and may not be correctly interpreted by assistive technologies.

Disabled Items

Menu items can be disabled to indicate that they are currently unavailable.

Open in a
new tab
MenuBar menuBar = new MenuBar();

menuBar.addItem("View");
MenuItem edit = menuBar.addItem("Edit");
edit.getElement().setAttribute("disabled", true);

MenuItem share = menuBar.addItem("Share");
SubMenu shareSubMenu = share.getSubMenu();
shareSubMenu.addItem("By email")
        .getElement()
        .setAttribute("disabled", true);
shareSubMenu.addItem("Get Link");

Checkable Menu Items

Menu items in drop-down menus can be configured as checkable, for toggling options on and off.

Open in a
new tab
MenuBar menuBar = new MenuBar();
MenuItem options = menuBar.addItem("Options");
SubMenu subItems = options.getSubMenu();

MenuItem saveItem = subItems.addItem("Save automatically");
saveItem.setCheckable(true);
saveItem.setChecked(true);
MenuItem notifyItem = subItems.addItem("Notify watchers");
notifyItem.setCheckable(true);
notifyItem.setChecked(false);

ComponentEventListener<ClickEvent<MenuItem>> listener = event -> {
    // System.out.println(event.getSource().isChecked());
};

saveItem.addClickListener(listener);
notifyItem.addClickListener(listener);
Note
Not a replacement for radio buttons
A Menu Bar with checkable items should not be used as a replacement for radio buttons in a form.

Dividers

You can use dividers to separate and group related content.

Open in a
new tab
MenuBar menuBar = new MenuBar();
MenuItem item = menuBar.addItem("Share");
SubMenu subMenu = item.getSubMenu();
subMenu.addItem("Facebook");
subMenu.addItem("Twitter");
subMenu.addItem("Instagram");
subMenu.add(new Hr());
subMenu.addItem("By email");
subMenu.addItem("Get link");
subMenu.add(new Hr());
subMenu.addItem("Set permissions");

Use dividers sparingly to avoid creating unnecessary visual clutter.

Warning
Content other than menu items not accessible
While it’s technically possible to put any UI element in a drop-down menu, including interactive components, they will not be accessible by keyboard or assistive technologies.

Open on Hover

The component can be configured to open drop-down menus on hover instead of on click.

Open in a
new tab
MenuBar menuBar = new MenuBar();
menuBar.setOpenOnHover(true);
addItems(menuBar);

Keyboard Usage

Top-Level Items

Interaction Keyboard Shortcut

Navigate between top-level items

left and right arrow keys

Open top-level menu

down / space / enter

Trigger top-level item with a menu

space / enter
Interaction Keyboard Shortcut

Navigate between items in a dropdown menu

top and down arrow keys

Open sub-menu

right / space / enter

Trigger menu item without a sub-menu

space / enter

Return to previous menu

left

Close the drop-down menu

esc

A Menu Bar with a single top-level item is essentially a drop-down button. This solution provides a better user experience and better accessibility than a regular Button paired with a Context Menu.

Open in a
new tab
MenuBar menuBar = new MenuBar();
MenuItem item = menuBar.addItem("John Smith");
SubMenu subMenu = item.getSubMenu();
subMenu.addItem("Profile");
subMenu.addItem("Account");
subMenu.addItem("Preferences");
subMenu.add(new Hr());
subMenu.addItem("Sign out");

So-called “combo buttons” can be created in a similar way, for example to provide a set of variations on an action.

Open in a
new tab
MenuBar menuBar = new MenuBar();
menuBar.addThemeVariants(MenuBarVariant.LUMO_ICON, MenuBarVariant.LUMO_PRIMARY);
menuBar.addItem("Save");
MenuItem item = menuBar.addItem(new Icon(VaadinIcon.CHEVRON_DOWN));
SubMenu subItems = item.getSubMenu();
subItems.addItem("Save as draft");
subItems.addItem("Save as copy");
subItems.addItem("Save and publish");

Best Practices

  • Menu Bar should not be used for navigation. Use tabs for switching between content, or anchor elements for regular navigation.

  • Menu Bar is not an input field. Use Select, Combo Box, or Radio Button instead.

Component Usage recommendations

Button

Regular Button component for individual actions.

Select

Drop-down input field.

Tabs

Tabs should be used to split content into sections that the user can switch between.

Context Menu

A generic drop-down menu that can be triggered from any component.

9AC623D3-FAAD-42D2-99EC-774F9A777E13