@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

The MDC Menu component is a spec-aligned menu component adhering to the Material Design menu specification. Menus require JavaScript to properly position themselves when opening.

Design & API Documentation

• Material Design guidelines: Menus
• Demo

Installation

npm install @material/menu

Usage

HTML Structure

A menu is initially hidden, appearing when opened via the JS API. It is appropriate for any display size.

<div class="mdc-menu" tabindex="-1">
  <ul class="mdc-menu__items mdc-list" role="menu" aria-hidden="true">
    <li class="mdc-list-item" role="menuitem" tabindex="0">
      A Menu Item
    </li>
    <li class="mdc-list-item" role="menuitem" tabindex="0">
      Another Menu Item
    </li>
  </ul>
</div>

Anchor To Parent

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

<div id="toolbar" class="toolbar mdc-menu-anchor">
  <div class="mdc-menu">
  ...
  </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-anchor">
  <button id="menu-button">Open Menu</button>
  <div class="mdc-menu">
  ...
  </div>
</div>

Disabled menu items

When used in components such as MDC Menu, list items can be disabled. To disable a list item, set aria-disabled property to "true", and set tabindex to "-1".

<div class="mdc-menu" tabindex="-1">
  <ul class="mdc-menu__items mdc-list" role="menu" aria-hidden="true">
    <li class="mdc-list-item" role="menuitem" tabindex="0">
      A Menu Item
    </li>
    <li class="mdc-list-item" role="menuitem" tabindex="-1" aria-disabled="true">
      Disabled Menu Item
    </li>
  </ul>
</div>

CSS Classes

CSS Class	Description
mdc-menu	Mandatory
mdc-menu--animating-open	Indicates the menu is currently animating open. This class is removed once the animation completes.
mdc-menu--open	Indicates the menu is currently open, or is currently animating open.
mdc-menu--animating-closed	Indicates the menu is currently animating closed. This class is removed once the animation completes.

JS Examples

  // Instantiation
  var menuEl = document.querySelector('#toolbar');
  var menu = new mdc.menu.MDCMenu(menuEl);
  var menuButtonEl = document.querySelector('#menu-button');

  // Toggle menu open
  menuButtonEl.addEventListener('click', function() {
    menu.open = !menu.open;
  });

  // Listen for selected item
  menuEl.addEventListener('MDCMenu:selected', function(evt) {
     var detail = evt.detail;
  });

  // Set Anchor Corner to Bottom End
  menu.setAnchorCorner(Corner.BOTTOM_END);

  // Turn off menu open animations
  menu.quickOpen = true;

MDCMenu

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

Property	Value Type	Description
open	Boolean	Proxies to the foundation's isOpen/(open, close) methods.
items	Array	Proxies to the foundation's container to query for all .mdc-list-item[role] elements.
itemsContainer	Element	Queries the foundation's root element for the mdc-menu__items container element.
quickOpen	Boolean	Proxies to the foundation's setQuickOpen() method.

Method Signature	Description
show({focusIndex: ?number}) => void	Proxies to the foundation's open() method. An optional config parameter allows the caller to specify which item should receive focus after the menu opens.
hide() => void	Proxies to the foundation's close() method.
setAnchorCorner(Corner) => void	Proxies to the foundation's setAnchorCorner(Corner) method.
setAnchorMargin(AnchorMargin) => void	Proxies to the foundation's setAnchorMargin(AnchorMargin) method.
getDefaultFoundation() => MDCMenuFoundation	Returns the foundation.

MDCMenuAdapter

Method Signature	Description
addClass(className: string) => void	Adds a class to the root element.
removeClass(className: string) => void	Removes a class from the root element.
hasClass(className: string) => boolean	Returns a boolean indicating whether the root element has a given class.
hasNecessaryDom() => boolean	Returns boolean indicating whether the necessary DOM is present (namely, the mdc-menu__items container).
getAttributeForEventTarget(target: EventTarget, attributeName: string) => string	Returns the value of a given attribute on an event target.
getInnerDimensions() => {width: number, height: number}	Returns an object with the items container width and height.
hasAnchor: () => boolean	Returns whether the menu has an anchor for positioning.
getAnchorDimensions() => {width: number, height: number, top: number, right: number, bottom: number, left: number}	Returns an object with the dimensions and position of the anchor (same semantics as DOMRect).
getWindowDimensions() => {width: number, height: number}	Returns an object with width and height of the page, in pixels.
getNumberOfItems() => number	Returns the number of item elements inside the items container. In our vanilla component, we determine this by counting the number of list items whose role attribute corresponds to the correct child role of the role present on the menu list element. For example, if the list element has a role of menu this queries for all elements that have a role of menuitem.
registerInteractionHandler(type: string, handler: EventListener) => void	Adds an event listener handler for event type type.
deregisterInteractionHandler(type: string, handler: EventListener) => void	Removes an event listener handler for event type type.
registerBodyClickHandler(handler: EventListener) => void	Adds an event listener handler for event type click.
deregisterBodyClickHandler(handler: EventListener) => void	Removes an event listener handler for event type click.
getIndexForEventTarget(target: EventTarget) => number	Checks to see if the target of an event pertains to one of the menu items, and if so returns the index of that item. Returns -1 if the target is not one of the menu items.
notifySelected(evtData: {index: number}) => void	Dispatches an event notifying listeners that a menu item has been selected. The function should accept an evtData parameter containing an object with an index property representing the index of the selected item. Implementations may choose to supplement this data with additional data, such as the item itself.
notifyCancel() => void	Dispatches an event notifying listeners that the menu has been closed with no selection made.
saveFocus() => void	Stores the currently focused element on the document, for restoring with restoreFocus.
restoreFocus() => void	Restores the previously saved focus state, by making the previously focused element the active focus again.
isFocused() => boolean	Returns a boolean value indicating whether the root element of the menu is focused.
focus() => void	Focuses the root element of the menu.
getFocusedItemIndex() => number	Returns the index of the currently focused menu item (-1 if none).
focusItemAtIndex(index: number) => void	Focuses the menu item with the provided index.
isRtl() => boolean	Returns boolean indicating whether the current environment is RTL.
setTransformOrigin(value: string) => void	Sets the transform origin for the menu element.
setPosition(position: {top: string, right: string, bottom: string, left: string}) => void	Sets the position of the menu element.
setMaxHeight(value: string) => void	Sets max-height style for the menu element.

MDCMenuFoundation

Method Signature	Description
setAnchorCorner(corder: Corner) => void	Sets the corner that the menu will be anchored to. See constants.js
setAnchorMargin(margin: AnchorMargin) => void	Sets the distance from the anchor point that the menu should be shown.
open({focusIndex: ?number}) => void	Opens the menu. Optionally accepts an object with a focusIndex parameter to indicate which list item should receive focus when the menu is opened.
close(evt: ?Event)	Closes the menu. Optionally accepts the event to check if the target is disabled before closing the menu.
isOpen() => boolean	Returns a boolean indicating whether the menu is open.
setQuickOpen(quickOpen: boolean) => void	Sets whether the menu should open and close without animation when the open/close methods are called.

Events

Event Name	Data	Description
MDCMenu:selected	{detail: {item: HTMLElement, 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.
MDCMenu:cancel	none	Event emitted when the menu is closed with no selection made (e.g. if the user hits Esc while it's open, or clicks somewhere else on the page).