14.0.0 • Published 5 months ago

@material/menu v14.0.0

Weekly downloads
61,840
License
MIT
Repository
github
Last release
5 months ago

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

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 ClassDescription
mdc-menuMandatory
mdc-menu--animating-openIndicates the menu is currently animating open. This class is removed once the animation completes.
mdc-menu--openIndicates the menu is currently open, or is currently animating open.
mdc-menu--animating-closedIndicates 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.

PropertyValue TypeDescription
openBooleanProxies to the foundation's isOpen/(open, close) methods.
itemsArrayProxies to the foundation's container to query for all .mdc-list-item[role] elements.
itemsContainerElementQueries the foundation's root element for the mdc-menu__items container element.
quickOpenBooleanProxies to the foundation's setQuickOpen() method.
Method SignatureDescription
show({focusIndex: ?number}) => voidProxies 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() => voidProxies to the foundation's close() method.
setAnchorCorner(Corner) => voidProxies to the foundation's setAnchorCorner(Corner) method.
setAnchorMargin(AnchorMargin) => voidProxies to the foundation's setAnchorMargin(AnchorMargin) method.
getDefaultFoundation() => MDCMenuFoundationReturns the foundation.

MDCMenuAdapter

Method SignatureDescription
addClass(className: string) => voidAdds a class to the root element.
removeClass(className: string) => voidRemoves a class from the root element.
hasClass(className: string) => booleanReturns a boolean indicating whether the root element has a given class.
hasNecessaryDom() => booleanReturns boolean indicating whether the necessary DOM is present (namely, the mdc-menu__items container).
getAttributeForEventTarget(target: EventTarget, attributeName: string) => stringReturns 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: () => booleanReturns 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() => numberReturns 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) => voidAdds an event listener handler for event type type.
deregisterInteractionHandler(type: string, handler: EventListener) => voidRemoves an event listener handler for event type type.
registerBodyClickHandler(handler: EventListener) => voidAdds an event listener handler for event type click.
deregisterBodyClickHandler(handler: EventListener) => voidRemoves an event listener handler for event type click.
getIndexForEventTarget(target: EventTarget) => numberChecks 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}) => voidDispatches 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() => voidDispatches an event notifying listeners that the menu has been closed with no selection made.
saveFocus() => voidStores the currently focused element on the document, for restoring with restoreFocus.
restoreFocus() => voidRestores the previously saved focus state, by making the previously focused element the active focus again.
isFocused() => booleanReturns a boolean value indicating whether the root element of the menu is focused.
focus() => voidFocuses the root element of the menu.
getFocusedItemIndex() => numberReturns the index of the currently focused menu item (-1 if none).
focusItemAtIndex(index: number) => voidFocuses the menu item with the provided index.
isRtl() => booleanReturns boolean indicating whether the current environment is RTL.
setTransformOrigin(value: string) => voidSets the transform origin for the menu element.
setPosition(position: {top: string, right: string, bottom: string, left: string}) => voidSets the position of the menu element.
setMaxHeight(value: string) => voidSets max-height style for the menu element.

MDCMenuFoundation

Method SignatureDescription
setAnchorCorner(corder: Corner) => voidSets the corner that the menu will be anchored to. See constants.js
setAnchorMargin(margin: AnchorMargin) => voidSets the distance from the anchor point that the menu should be shown.
open({focusIndex: ?number}) => voidOpens 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() => booleanReturns a boolean indicating whether the menu is open.
setQuickOpen(quickOpen: boolean) => voidSets whether the menu should open and close without animation when the open/close methods are called.

Events

Event NameDataDescription
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:cancelnoneEvent 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).
@material/data-table@material/select@material/mwc-menuplaytwo-core-cms-sections@zentek/menumdwrapper@beezydev/menumaterial-components-web@everything-registry/sub-chunk-584@ied/task@inovex.de/elements@hail-mary-project/button@infinitebrahmanuniverse/nolb-_mate@materials-elements/core@materials-elements/site@materials-ui/core@materials-ui/site@material-design/svelte@material/react-menu@leanup/material-core@fushihara/vue-todoist-list@gmvdev/materials@mcwv/menu@mhamrah/svelte-material-ui@mdc-stencil/menu@netdata/dashboard@smui/menu@types/material__menu@openremote/or-mwc-components@pmwcs/menu@plonquo/ember-material-components@preact-material-components/menu@robertkern/vue-material@rmwc/menu@o-rango/orango-material-design@pitaya-components/menu@xolvio/plate-ui-comments@vue-cruder/ui@xdam/ember-partialsember-cli-mdc-menuember-material-components@emuanalytics/flow-rdforange-bees-angular-material-table@arterial/menu-surface@aurelia2-mdc-web/menu@aurelia-mdc-web/menugesdisc-componentspreact-material-componentspreact-material-components-mgr@authentic/mwc-menubw-materialaurelia-mdc-uiaurelia-material-ui@angular/material@angular/material-experimentalcomponents-library-v1@codeadraas/vue3-materialreact-material-web-componentsreact-mdc@batchforce/coreimpetus-context-menucsr-appidm-reservation-search-results-details-libregila-ui@bringhub/fabric.jshail-mary-projectcollectiveone-webcomponents@dev.mohe/mwc-menu@detachhead/smui-menu@defense-unicorns/unicorn-ui@cytracom/sdktrustylespanidea-matertial-tablesvelte-arcadiasvelte-ts-ui-libmaterial-imbamaterial-toolboxuui-componentsvoyager-componentsvue-material-design-componentstest-rsmdcmyg-menu
14.0.0

2 years ago

13.0.0

3 years ago

12.0.0

3 years ago

11.0.0

3 years ago

10.0.0

3 years ago

9.0.0

3 years ago

8.0.0

3 years ago

7.0.0

4 years ago

6.0.0

4 years ago

5.1.0

4 years ago

5.0.0

4 years ago

4.0.0

4 years ago

3.2.0

5 years ago

4.0.0-canary.1

5 years ago

4.0.0-canary.0

5 years ago

4.0.0-alpha.0

5 years ago

3.1.0

5 years ago

3.1.0-alpha.0

5 years ago

3.0.0

5 years ago

3.0.0-alpha.1

5 years ago

3.0.0-alpha.0

5 years ago

2.3.0

5 years ago

2.2.0

5 years ago

3.0.0-0

5 years ago

2.1.1

5 years ago

2.0.0

5 years ago

1.1.1

5 years ago

1.1.0

5 years ago

1.0.1

5 years ago

1.0.0

5 years ago

1.0.0-1

5 years ago

1.0.0-0

5 years ago

0.44.1

5 years ago

0.44.0

5 years ago

0.43.0

5 years ago

0.42.1

5 years ago

0.42.0

5 years ago

0.41.0

5 years ago

0.40.1

6 years ago

0.40.0

6 years ago

0.39.3

6 years ago

0.39.2

6 years ago

0.39.1

6 years ago

0.39.0

6 years ago

0.39.0-0

6 years ago

0.38.0

6 years ago

0.37.1

6 years ago

0.36.1

6 years ago

0.35.0

6 years ago

0.34.0

6 years ago

0.33.0

6 years ago

0.31.0

6 years ago

0.30.0

6 years ago

0.29.0

6 years ago

0.28.0

6 years ago

0.27.0

6 years ago

0.25.0

6 years ago

0.24.0

6 years ago

0.23.0

7 years ago

0.4.8

7 years ago

0.4.7

7 years ago

0.4.6

7 years ago

0.4.5

7 years ago

0.4.4

7 years ago

0.4.3

7 years ago

0.4.2

7 years ago

0.4.1

7 years ago

0.4.0

7 years ago

0.3.0

7 years ago

0.2.7

7 years ago

0.2.6

7 years ago

0.2.5

7 years ago

0.2.4

7 years ago

0.2.3

7 years ago

0.2.2

7 years ago

0.2.1

7 years ago

0.2.0

7 years ago

0.1.3

7 years ago

0.1.2

7 years ago

0.1.1

7 years ago

0.1.0

7 years ago