> Markdown version of [Menu Bar](https://vaadin.com/docs/v14/ds/components/menu-bar). Section index: [llms.txt](https://vaadin.com/docs/v14/ds/llms.txt) # 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. `MenuBarBasic.java` ```java MenuBar menuBar = new MenuBar(); Text selected = new Text(""); ComponentEventListener> 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: `MenuBarStyles.java` ```java 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](https://vaadin.com/docs/v14/ds/components/button.md#styles), 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](#drop-down-and-combo-buttons). | | 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](https://vaadin.com/docs/v14/ds/customization/component-variants.md#custom-variants). 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](https://vaadin.com/docs/v14/ds/customization/custom-theme.md#vaadin-component-styles) for details how to add style sheets for those components. `MenuBarCustomTheme.java` ```java 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"); ``` `vaadin-context-menu-item.css` ```css :host([theme~='custom-theme']) { text-transform: uppercase; } ``` `vaadin-menu-bar-button.css` ```css :host([theme~='custom-theme']) { text-transform: uppercase; } ``` ## Overflow Items that don’t fit into the current width of the menu bar automatically collapse into an overflow menu at the end: `MenuBarOverflow.java` ```java 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); ``` ## Menu Item Features ### Icons Menu items can have icons in addition to, or instead of text. `MenuBarIcons.java` ```java 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. `MenuBarIconOnly.java` ```java 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. `MenuBarDisabled.java` ```java 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. `MenuBarCheckable.java` ```java 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> 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](https://vaadin.com/docs/v14/ds/components/radio-button.md) in a form. ## Dividers You can use dividers to separate and group related content. `MenuBarDividers.java` ```java 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. `MenuBarOpenOnHover.java` ```java 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` | ### Menu-Items | 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` | ## Drop-Down and "Combo" Buttons 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](https://vaadin.com/docs/v14/ds/components/button.md) paired with a [Context Menu](https://vaadin.com/docs/v14/ds/components/context-menu.md). `MenuBarDropDown.java` ```java 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. `MenuBarComboButtons.java` ```java 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](https://vaadin.com/docs/v14/ds/components/tabs.md) for switching between content, or anchor elements for regular navigation. - Menu Bar is not an input field. Use [Select](https://vaadin.com/docs/v14/ds/components/select.md), [Combo Box](https://vaadin.com/docs/v14/ds/components/combo-box.md), or [Radio Button](https://vaadin.com/docs/v14/ds/components/radio-button.md) instead. ## Related Components | Component | Usage recommendations | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | [Button](https://vaadin.com/docs/v14/ds/components/button.md) | Regular Button component for individual actions. | | [Select](https://vaadin.com/docs/v14/ds/components/select.md) | Drop-down input field. | | [Tabs](https://vaadin.com/docs/v14/ds/components/tabs.md) | Tabs should be used to split content into sections that the user can switch between. | | [Context Menu](https://vaadin.com/docs/v14/ds/components/context-menu.md) | A generic drop-down menu that can be triggered from any component. | `9AC623D3-FAAD-42D2-99EC-774F9A777E13`