@material/menu

What is @material/menu?

@material/menu is a Material Design menu component for the web. It provides a simple way to create menus that follow the Material Design guidelines, including support for nested menus, keyboard navigation, and accessibility features.

What are @material/menu's main functionalities?

Basic Menu

This code demonstrates how to create a basic menu using the @material/menu package. It initializes a menu component and opens it.

import {MDCMenu} from '@material/menu';

const menu = new MDCMenu(document.querySelector('.mdc-menu'));
menu.open = true;

Menu with Items

This code shows how to create a menu with items and add an event listener to handle item clicks.

import {MDCMenu} from '@material/menu';

const menu = new MDCMenu(document.querySelector('.mdc-menu'));
menu.open = true;

const listItem = document.querySelector('.mdc-list-item');
listItem.addEventListener('click', () => {
  console.log('Item clicked');
});

Nested Menus

This code demonstrates how to create nested menus using the @material/menu package. It initializes a parent menu and a child menu, and opens the child menu when an item in the parent menu is clicked.

import {MDCMenu} from '@material/menu';

const parentMenu = new MDCMenu(document.querySelector('.mdc-menu-parent'));
const childMenu = new MDCMenu(document.querySelector('.mdc-menu-child'));

parentMenu.open = true;

const parentItem = document.querySelector('.mdc-list-item-parent');
parentItem.addEventListener('click', () => {
  childMenu.open = true;
});

Other packages similar to @material/menu

react-select

react-select is a flexible and customizable menu component for React applications. It provides a wide range of features including multi-select, async options, and customizable styles. Compared to @material/menu, react-select is more focused on providing a rich set of features for select inputs rather than general-purpose menus.

rc-menu

rc-menu is a React component for creating menus. It supports nested menus, keyboard navigation, and customizable styles. While it offers similar functionality to @material/menu, rc-menu is specifically designed for React applications and provides more flexibility in terms of customization.

semantic-ui-react

semantic-ui-react is the official React integration for Semantic UI. It includes a Menu component that provides a wide range of features including vertical and horizontal menus, submenus, and item grouping. Compared to @material/menu, semantic-ui-react offers a more comprehensive set of UI components and is designed to work seamlessly with the Semantic UI framework.

README

Menus

A menu displays a list of choices on a temporary surface. They appear when users interact with a button, action, or other control.

Important Changes

Menu is currently being updated to use the new List implementation. For now, please continue to use the old implementation (mdc-deprecated-list and associated DOM/classes) instead of the new one (mdc-list).

See the List documentation for more information.

Design & API Documentation

• Material Design guidelines: Menus
• Demo

Installation

npm install @material/menu

Basic Usage

HTML Structure

<div class="mdc-menu mdc-menu-surface">
  <ul class="mdc-deprecated-list" role="menu" aria-hidden="true" aria-orientation="vertical" tabindex="-1">
    <li class="mdc-deprecated-list-item" role="menuitem">
      <span class="mdc-deprecated-list-item__ripple"></span>
      <span class="mdc-deprecated-list-item__text">A Menu Item</span>
    </li>
    <li class="mdc-deprecated-list-item" role="menuitem">
      <span class="mdc-deprecated-list-item__ripple"></span>
      <span class="mdc-deprecated-list-item__text">Another Menu Item</span>
    </li>
  </ul>
</div>

Styles

@use "@material/list/mdc-list";
@use "@material/menu-surface/mdc-menu-surface";
@use "@material/menu/mdc-menu";

JavaScript Instantiation

import {MDCMenu} from '@material/menu';

const menu = new MDCMenu(document.querySelector('.mdc-menu'));
menu.open = true;

See Importing the JS component for more information on how to import JavaScript.

Variants

Selection Group Menu

Menus can contain a group of list items that can represent the selection state of elements within the group.

<div class="mdc-menu mdc-menu-surface" id="demo-menu">
  <ul class="mdc-deprecated-list" role="menu" aria-hidden="true" aria-orientation="vertical" tabindex="-1">
    <li>
      <ul class="mdc-menu__selection-group">
        <li class="mdc-deprecated-list-item" role="menuitem">
          <span class="mdc-deprecated-list-item__ripple"></span>
          <span class="mdc-deprecated-list-item__graphic mdc-menu__selection-group-icon">
            ...
          </span>
          <span class="mdc-deprecated-list-item__text">Single</span>
        </li>
        <li class="mdc-deprecated-list-item" role="menuitem">
          <span class="mdc-deprecated-list-item__ripple"></span>
          <span class="mdc-deprecated-list-item__graphic mdc-menu__selection-group-icon">
           ...
          </span>
          <span class="mdc-deprecated-list-item__text">1.15</span>
        </li>
      </ul>
    </li>
    <li class="mdc-deprecated-list-divider" role="separator"></li>
    <li class="mdc-deprecated-list-item" role="menuitem">
      <span class="mdc-deprecated-list-item__ripple"></span>
      <span class="mdc-deprecated-list-item__text">Add space before paragraph</span>
    </li>
    ...
  </ul>
</div>

Disabled Menu Items

Menu items can be disabled by adding the mdc-deprecated-list-item--disabled modifier class (from MDC List). Disabled menu items will be excluded from keyboard navigation.

Anchors and Positioning

Anchored To Parent

The menu can be positioned to automatically anchor to a parent element when opened.

<div id="toolbar" class="toolbar mdc-menu-surface--anchor">
  <div class="mdc-menu mdc-menu-surface">
  ...
  </div>
</div>

Anchor To Element Within Wrapper

The menu can be positioned to automatically anchor to another element, by wrapping the other element with the anchor class.

<div id="demo-menu" class="mdc-menu-surface--anchor">
  <button id="menu-button">Open Menu</button>
  <div class="mdc-menu mdc-menu-surface">
  ...
  </div>
</div>

Fixed Position

The menu can use fixed positioning when being displayed.

<div class="mdc-menu mdc-menu-surface">
...
</div>

// ...
menu.setFixedPosition(true);

Absolute Position

The menu can use absolutely positioned when being displayed.

<div class="mdc-menu mdc-menu-surface">
...
</div>

// ...
menu.setAbsolutePosition(100, 100);

Style Customization

CSS Classes

CSS Class	Description
mdc-menu	Required on the root element
mdc-menu-surface	Required on the root element. See mdc-menu-surface documentation for other mdc-menu-surface classes.
mdc-deprecated-list	Required on the nested ul element. See mdc-list documentation for other mdc-deprecated-list classes.
mdc-menu__selection-group	Used to wrap a group of mdc-deprecated-list-item elements that will represent a selection group.
mdc-menu__selection-group-icon	Required when using a selection group to indicate which item is selected. Should contain an icon or svg that indicates the selected state of the list item.
mdc-menu-item--selected	Used to indicate which element in a selection group is selected.

Sass Mixins

Mixin	Description
width($width)	Used to set the width of the menu. When used without units (e.g. 4 or 5) it computes the width by multiplying by the base width (56px). When used with units (e.g. 240px, 15%, or calc(200px + 10px) it sets the width to the exact value provided.
min-width($min-width)	Sets the min-width of the menu. Use with units (e.g. 240px, 15%, or calc(200px + 10px) only.

See Menu Surface and List documentation for additional style customization options.

Accessibility

Please see Menu Button WAI-ARIA practices article for details on recommended Roles, States, and Properties for menu button (button that opens a menu).

With focus on the menu button:

• Enter, Space & Down Arrow opens the menu and places focus on the first menu item.
• Up Arrow opens the menu and moves focus to the last menu item.
• The focus is set to list root element (where role="menu" is set) when clicked or touched. MDC List handles the keyboard navigation once it receives the focus.

Use setDefaultFocusState method to set default focus state that will be focused every time when menu is opened.

Focus state	Description
DefaultFocusState.FIRST_ITEM	Focuses the first menu item. Set this when menu button receives Enter, Space, Down Arrow.
DefaultFocusState.LAST_ITEM	Focuses the last menu item. Set this when menu button receives Up arrow.
DefaultFocusState.LIST_ROOT	Focuses the list root. Set this when menu button Clicked or Touched.
DefaultFocusState.NONE	Does not change the focus. Set this if you do not want the menu to grab focus on open. (Autocomplete dropdown menu, for example).

MDCMenu Properties and Methods

See Importing the JS component for more information on how to import JavaScript.

Property	Value Type	Description
open	Boolean	Proxies to the menu surface's open property.
items	Array<Element>	Proxies to the list to query for all .mdc-deprecated-list-item elements.
quickOpen	Boolean	Proxies to the menu surface quickOpen property.
wrapFocus	Boolean	Proxies to list's wrapFocus property.
hasTypeahead	Boolean	Proxies to the list's hasTypeahead property.

Method Signature	Description
setAnchorCorner(Corner) => void	Proxies to the menu surface's setAnchorCorner(Corner) method.
setAnchorMargin(Partial<MDCMenuDistance>) => void	Proxies to the menu surface's setAnchorMargin(Partial<MDCMenuDistance>) method.
setAbsolutePosition(x: number, y: number) => void	Proxies to the menu surface's setAbsolutePosition(x: number, y: number) method.
setFixedPosition(isFixed: boolean) => void	Proxies to the menu surface's setFixedPosition(isFixed: boolean) method.
setSelectedIndex(index: number) => void	Sets the list item to the selected state at the specified index.
setIsHoisted(isHoisted: boolean) => void	Proxies to the menu surface's setIsHoisted(isHoisted: boolean) method.
setAnchorElement(element: Element) => void	Proxies to the menu surface's setAnchorElement(element) method.
getOptionByIndex(index: number) => Element | null	Returns the list item at the index specified.
getPrimaryTextAtIndex(index: number) => string	Returns the primary text at the index specified.
getDefaultFoundation() => MDCMenuFoundation	Returns the foundation.
setDefaultFocusState(focusState: DefaultFocusState) => void	Sets default focus state where the menu should focus every time when menu is opened. Focuses the list root (DefaultFocusState.LIST_ROOT) element by default.
setEnabled(index: number, isEnabled: boolean) => void	Sets the enabled state to isEnabled for the menu item at given index.
layout() => void	Proxies to the list's layout method.
typeaheadMatchItem(nextChar: string) => number	Adds a character to the typeahead buffer and returns index of the next item in the list matching the buffer.

See Menu Surface and List documentation for more information on proxied methods and properties.

Usage within Web Frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a Menu for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.

MDCMenuAdapter

Method Signature	Description
addClassToElementAtIndex(index: number, className: string) => void	Adds the className class to the element at the index specified.
removeClassFromElementAtIndex(index: number, className: string) => void	Removes the className class from the element at the index specified.
addAttributeToElementAtIndex(index: number, attr: string, value: string) => void	Adds the attr attribute with value value to the element at the index specified.
removeAttributeFromElementAtIndex(index: number, attr: string) => void	Removes the attr attribute from the element at the index specified.
elementContainsClass(element: Element, className: string) => boolean	Returns true if the element contains the className class.
closeSurface(skipRestoreFocus?: boolean) => void	Closes the menu surface, skipping restoring focus to the previously focused element if skipRestoreFocus is true.
getElementIndex(element: Element) => number	Returns the index value of the element.
notifySelected(index: number) => void	Emits a MDCMenu:selected event for the element at the index specified.
getMenuItemCount() => number	Returns the menu item count.
focusItemAtIndex(index: number)	Focuses the menu item at given index.
focusListRoot() => void	Focuses the list root element.
getSelectedSiblingOfItemAtIndex(index: number) => number	Returns selected list item index within the same selection group which is a sibling of item at given index.
isSelectableItemAtIndex(index: number) => boolean	Returns true if menu item at specified index is contained within an .mdc-menu__selection-group element.

MDCMenuFoundation

Method Signature	Description
handleKeydown(evt: Event) => void	Event handler for the keydown events within the menu.
handleItemAction(listItem: Element) => void	Event handler for list's action event.
handleMenuSurfaceOpened() => void	Event handler for menu surface's opened event.
setDefaultFocusState(focusState: DefaultFocusState) => void	Sets default focus state where the menu should focus every time when menu is opened. Focuses the list root (DefaultFocusState.LIST_ROOT) element by default.
setSelectedIndex(index: number) => void	Selects the list item at given index.
setEnabled(index: number, isEnabled: boolean) => void	Sets the enabled state of the menu item at given index.

Events

Event Name	Data	Description
MDCMenu:selected	{detail: {item: Element, index: number}}	Used to indicate when an element has been selected. This event also includes the item selected and the list index of that item.

Changelog

14.0.0 (2022-04-27)

Bug Fixes

• button: update HCM shim to use the existing focus-ring (a657abb)
• checkbox: Add explicit system color for checkmark in HCM. (8c4da22)
• checkbox: move forced-colors theme out of static styles (bbd1126)
• checkbox: Update checkbox theme styles mixin to accept css vars (c14e977)
• chips: Fix typography selector in GMDC-Wiz chips theming (43c7d87)
• datatable: Adjust data table last row border-radius to support setting row background-color. (ba78e87)
• dialog: Render dividers in Firefox 94 on Windows HCM (fae6c65)
• dialog: Set default z-index for close button in FloatingSheet dialog. (3366a71)
• fab: Add focus ring in HCM. (d57ec74)
• focus-ring: add 2d padding customizability, RTL bugfix (f81fb1d)
• focus-ring: box-sizing bugfix to content-box. If box-sizing border-box is inherited the ring spacing will collapse. (e58552c)
• focus-ring: ignore pointer events (3ef470e)
• focus-ring: RTL bugfix (e00181e)
• iconbutton: Fixed max width and height for high contrast mode focus ring on icon buttons. Display only in forced colors mode. (cf42927)
• iconbutton: Set icon button ripple z-index to -1. (586e740)
• list: Improve a11y for multi-select lists (9736ddc)
• list: Remove conflicting validation for checkbox list in setEnabled (353ca7e)
• list: Update lastSelectedIndex when toggling a checkbox range (dcba26f)
• menusurface: Add a getOwnerDocument() method to MDCMenuSurfaceAdapter to provide a reference to the document that owns the menu surface DOM element. (3486659)
• radio: Fix disabled state in Firefox Windows high contrast mode (23043ac)
• radio: Modify theme styles Sass mixin validation to validate only keys (390220e)
• select: Add border to select menu in HCM. (5d80969)
• select: revert down/up arrow on anchor changing selected index (43d08ba)
• slider: Fix bug where secondary click moves slider thumb. (3ab9565)
• slider: Fix IE11 bug - unset is unsupported in IE. (f460e23)
• slider: In updateUI, fix behavior to match jsdoc claim that when thumb param is undefined it updates both thumbs. Input attributes were not being updated at all. (cc4ed13)
• slider: Make the slider errors easier to debug by providing all relevant values in the error message. (8687937)
• snackbar: address Trusted Types violation (cbd9358)
• tooltip: Adjusts logic in validateTooltipWithCaretDistances method. (3e30054)
• typography: Fixes typography theme-styles mixin... the value being retreived from the $theme map and css property name was swapped. The mixin would request font-size/font-weight/letter-spacing from the $theme map (which expects size/weight/tracking)... so these values would always be null. (32b3913)
• Remove /** @override */ tags from TypeScript code. (c3cdff0)
• Simplify MDCAttachable interface to be any object (Function) that has attachTo. (05db65e)
• Snackbar action button ripple color is applied to the ripple element. (4e66fb2)
• Work around bug in Sass (037285f), closes sass/sass#3259
• switch: Restore Firefox 94 HCM outlines (39cf14b)
• textfield: Fix breaking tests due to no valid pointerId being associated with pointer events. (15db4f1)
• tooltip: Only sends notification of a tooltip being hidden if showTimeout is not set (indicating that this tooltip is about to be re-shown). (6ca8b8f)

Features

• banner: Add disableAutoClose params for both banner actions to prevent the banner buttons from automatically closing the banner. Add adapter #notifyActionClicked method. (b094eaa)
• chips: add focus ring styles (783f6fd)
• chips: Added elevation tint layer color support in chips (c78ff04)
• data-table: separate table structure into its own mixin (9f9d928)
• dialog: Add styling for floating sheets (78305b6)
• dialog: Add styling for floating sheets with content padding (3e20c1d)
• Dialog: Adds an API to hide the header for GMDC Fullscreen Dialog in non-fullscreen mode (ab4aba1)
• Dialog: Adds an API to set custom position for GMDC Dialog (ea9b5b4)
• Dialog: Adds an API to set custom z-index for GMDC Dialog (96ea061)
• focus-ring: added a new mixin so we can override just the focus-ring color (641ed08)
• focus-ring: added a new mixin so we can override just the focus-ring radius (7321d62)
• iconbutton: Add link icon button Sass. (9803d2d)
• mdc-list: introduce selection change event (7d8ea46)
• menu: allow preferentially opening surface below anchor (261f2db)
• MenuSurface: Add opening event for menus. (53b3cad)
• select: Add theming mixin boilerplate code to select (ae8a6a3)
• select: Add validation getter methods. (bdf1d37)
• select: Added theme mixins to MDC select (dcfe49c)
• slider: Add minRange param to range sliders to request a minimum gap between the two thumbs. (8fffcb5)
• slider: Add an option to hide focus styles after pointer interaction. (ec54d90)
• slider: Keep the slider value indicator within the bounds of the slider if possible. (c047f7c)
• state: make context aware (b2fe352)
• switch: Add high contrast mode focus ring to switch (f31a833)
• text-field: Add theming mixin boilerplate code to text-field (eb382f3)
• text-field: Added theme mixins to MDC text field (344d528)
• textfield: adding input-font-size mixin (207230e)
• theme: allow custom property strings in theme.validate-theme() (4e372fb)
• add new class and mixin for open state of a menu item (9a02b6e)
• Indicate which thumb valueToAriaValueTextFn and valueToValueIndicatorTextFn functions are called for. (b6510c8)
• textfield: adding input-font-family mixin (991fb99)
• Describe how to add child lists into a list item. (758ce31)

BREAKING CHANGES

• MenuSurface: Adds #notifyOpening method to menu surface adapter.

PiperOrigin-RevId: 444830518

• slider: Adds #getValueIndicatorContainerWidth method to slider adapter.

PiperOrigin-RevId: 419837612