@shortcm/menu

The Material Components for the web menu component

Usage no npm install needed!

<script type="module">
  import shortcmMenu from 'https://cdn.skypack.dev/@shortcm/menu';
</script>

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.

Design & API Documentation

Installation

npm install @material/menu

Basic Usage

HTML Structure

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

Styles

@import "@material/list/mdc-list";
@import "@material/menu-surface/mdc-menu-surface";
@import "@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" tabindex="-1" id="demo-menu">
  <ul class="mdc-list" role="menu" aria-hidden="true" aria-orientation="vertical">
    <li>
      <ul class="mdc-menu__selection-group">
        <li class="mdc-list-item" role="menuitem">
          <span class="mdc-list-item__graphic mdc-menu__selection-group-icon">
            ...
          </span>
          <span class="mdc-list-item__text">Single</span>
        </li>
        <li class="mdc-list-item" role="menuitem">
          <span class="mdc-list-item__graphic mdc-menu__selection-group-icon">
           ...
          </span>
          <span class="mdc-list-item__text">1.15</span>
        </li>
      </ul>
    </li>
    <li class="mdc-list-divider" role="separator"></li>
    <li class="mdc-list-item" role="menuitem">
      <span class="mdc-list-item__text">Add space before paragraph</span>
    </li>
    ...
  </ul>
</div>

Disabled Menu Items

Menu items can be disabled by adding the mdc-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.hoistMenuToBody(); // Not required if the menu is already positioned on the body.
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-list Required on the nested ul element. See mdc-list documentation for other mdc-list classes.
mdc-menu__selection-group Used to wrap a group of mdc-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
mdc-menu-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.

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

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 Proxies to the list to query for all .mdc-list-item elements.
quickOpen Boolean Proxies to the menu surface quickOpen property.
wrapFocus Boolean Proxies to list's wrapFocus 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.
hoistMenuToBody() => void Proxies to the menu surface's hoistMenuToBody() method.
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.
getDefaultFoundation() => MDCMenuFoundation Returns the foundation.

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() => void Closes the menu surface.
getElementIndex(element: Element) => number Returns the index value of the element.
getParentElement(element: Element) => Element \| null Returns the .parentElement element of the element provided.
getSelectedElementIndex(element: Element) => number Returns the index value of the element within the selection group provided, element that contains the mdc-menu-item--selected class.
notifySelected(index: number) => void Emits a MDCMenu:selected event for the element at the index specified.

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.

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.