0.27.0 • Published 2 years ago

@material/mwc-menu v0.27.0

Weekly downloads
6,528
License
Apache-2.0
Repository
github
Last release
2 years ago

<mwc-menu> Published on npm

IMPORTANT: The Material Web Components are a work in progress and subject to major changes until 1.0 release.

Menus display a list of choices on temporary surfaces.

Material Design Guidelines: menus

Demo

Installation

npm install @material/mwc-menu

NOTE: The Material Web Components are distributed as ES2017 JavaScript Modules, and use the Custom Elements API. They are compatible with all modern browsers including Chrome, Firefox, Safari, Edge, and IE11, but an additional tooling step is required to resolve bare module specifiers, as well as transpilation and polyfills for IE11. See here for detailed instructions.

Example usage

Basic

Note, mwc-menu internally uses mwc-list, so its main slot has the same interface as the main slot of a mwc-list.

<div style="position: relative;">
  <mwc-button id="button" raised label="Open Menu"></mwc-button>
  <mwc-menu id="menu">
    <mwc-list-item>Item 0</mwc-list-item>
    <mwc-list-item>Item 1</mwc-list-item>
    <mwc-list-item>Item 2</mwc-list-item>
    <mwc-list-item>Item 3</mwc-list-item>
  </mwc-menu>
</div>

<script type="module">
  import '@material/mwc-menu/mwc-menu.js';
  import '@material/mwc-list/mwc-list-item.js';

  // anchor must share a parent with menu that is `position: relative`
  menu.anchor = button;

  button.addEventListener('click', function (e) {
    menu.open = true;
    // alternatively you can use menu.show();
  });
</script>

Activatable

<div style="position: relative;">
  <mwc-button id="button" raised label="Open Menu"></mwc-button>
  <mwc-menu activatable id="menu">
    <mwc-list-item>Item 0</mwc-list-item>
    <mwc-list-item selected activated>Item 1</mwc-list-item>
    <mwc-list-item>Item 2</mwc-list-item>
    <mwc-list-item>Item 3</mwc-list-item>
  </mwc-menu>
</div>

Multi-selectable (activatable)

<div style="position: relative;">
  <mwc-button id="button" raised label="Open Menu"></mwc-button>
  <mwc-menu activatable multi id="menu">
    <mwc-list-item>Item 0</mwc-list-item>
    <mwc-list-item selected activated>Item 1</mwc-list-item>
    <mwc-list-item>Item 2</mwc-list-item>
    <mwc-list-item selected activated>Item 3</mwc-list-item>
  </mwc-menu>
</div>

Absolute

<!--
  Note: no position: relative; This will make x and y relative to whatever
  ancestor is position: relative;
-->
<div>
  <mwc-button id="button" raised label="Open Menu"></mwc-button>
  <mwc-menu absolute x="50" y="100" id="menu">
    <mwc-list-item>Item 0</mwc-list-item>
    <mwc-list-item>Item 1</mwc-list-item>
    <mwc-list-item>Item 2</mwc-list-item>
    <mwc-list-item>Item 3</mwc-list-item>
  </mwc-menu>
</div>
<!-- No anchor associated -->

Fixed

<div>
  <mwc-button id="button" raised label="Open Menu"></mwc-button>
  <mwc-menu fixed id="menu">
    <mwc-list-item>Item 0</mwc-list-item>
    <mwc-list-item>Item 1</mwc-list-item>
    <mwc-list-item>Item 2</mwc-list-item>
    <mwc-list-item>Item 3</mwc-list-item>
  </mwc-menu>
</div>
<script type="module">
  import '@material/mwc-menu/mwc-menu.js';
  import '@material/mwc-list/mwc-list-item.js';

  menu.anchor = button;

  button.addEventListener('click', function (e) {
    menu.open = true;
    // alternatively you can use menu.show();
  });
</script>

Selection Groups

Adding a group to your mwc-list-items will associate them with other [mwc-list-item]s in the same group and make selection function similarly to a radio group.

<style>
  /* Hide the icon of unselected menu items that are in a group */
  #menu > [mwc-list-item][group]:not([selected]) [slot="graphic"] {
    display: none;
  }
</style>
<div style="position:relative;">
  <mwc-button id="button" raised label="Open Menu"></mwc-button>

  <mwc-menu multi id="menu">
    <mwc-list-item group="a" graphic="icon">
      <mwc-icon slot="graphic">check</mwc-icon>
      <span>Item 0</span>
    </mwc-list-item>
    <mwc-list-item group="a" graphic="icon" selected>
      <mwc-icon slot="graphic">check</mwc-icon>
      <span>Item 1</span>
    </mwc-list-item>
    <mwc-list-item group="a" graphic="icon">
      <mwc-icon slot="graphic">check</mwc-icon>
      <span>Item 2</span>
    </mwc-list-item>
    <li divider role="separator"></li>
    <mwc-list-item group="b" graphic="icon" selected>
      <mwc-icon slot="graphic">check</mwc-icon>
      <span>Item 3</span>
    </mwc-list-item>
    <mwc-list-item group="b" graphic="icon">
      <mwc-icon slot="graphic">check</mwc-icon>
      <span>Item 4</span>
    </mwc-list-item>
  </mwc-menu>
</div>

Styled

mwc-menu internally uses mwc-list, and all CSS custom properties exposed by mwc-list apply here as well.

<style>
  #menu {
    --mdc-menu-min-width: 200px;
    --mdc-menu-item-height: 30px;
    --mdc-theme-surface: aliceblue;

    /* inherits the styles of mwc-list internally */
    --mdc-theme-primary: blue;
    --mdc-list-vertical-padding: 0px;
    --mdc-list-side-padding: 30px;
  }
</style>
<div style="position: relative;">
  <mwc-button id="button" raised label="Open Menu"></mwc-button>
  <mwc-menu activatable multi id="menu">
    <mwc-list-item selected activated>Item 0</mwc-list-item>
    <mwc-list-item selected activated>Item 1</mwc-list-item>
    <mwc-list-item>Item 2</mwc-list-item>
    <mwc-list-item>Item 3</mwc-list-item>
  </mwc-menu>
</div>

API

Slots

NameDescription
defaultContent to display in the menus internal <mwc-list> element.

mwc-menu internally uses mwc-list, so the default slot has the same interface as the default slot of mwc-list.

Properties/Attributes

NameTypeDefaultDescription
openbooleanfalseWhether the menu should open and display.
anchorHTMLElement\|nullnullDetermines from which element the floating menu should calculate sizing and position offsets. In the default case, both mwc-menu and the anchor should share a parent with position:relative. Changing anchor typically requires absolute or fixed.
cornerCorner*"TOP_START"Corner of the anchor from which the menu should position itself.
menuCornerMenuCorner**"START"Horizontal corner of the menu from which the menu should position itself. NOTE: Only horizontal corners are supported.
quickbooleanfalseWhether to skip the opening animation.
absolutebooleanfalseMakes the menu's position absolute which will be relative to whichever ancestor has position:relative. Setting x and y will modify the menu's left and top. Setting anchor will attempt to position the menu to the anchor.
fixedbooleanfalseMakes the menu's position fixed which will be relative to the window. Setting x and y will modify the menu's left and top. Setting anchor will attempt to position the menu to the anchor's immediate position before opening.
xnumber\|nullnullSets horizontal position when absolute. When given an anchor, sets horizontal position relative to anchor at given corner. Requires y not to be null.
ynumber\|nullnullSets vertical position when absolute. When given an anchor, sets vertical position relative to anchor at given corner. Requires x not to be null.
forceGroupSelectionbooleanfalseForces a menu group to have a selected item by preventing deselection of menu items in menu groups via user interaction.
defaultFocusDefaultFocusState***"LIST_ROOT"Item to focus upon menu open.
fullwidthbooleanfalseSets surface width to 100%.
stayOpenOnBodyClickbooleanfalsePrevents the menu from closing when clicking outside the menu.
wrapFocusbooleanfalseProxies to mwc-list's wrapFocus property.
innerAriaLabelstring\|nullnullProxies to mwc-list's innerAriaLabel property.
innerRole"menu"\|"listbox""menu"Proxies to mwc-list's innerRole property.
multibooleanfalseProxies to mwc-list's multi property.
activatablebooleanfalseProxies to mwc-list's activatable property.
itemsListItemBase[] (readonly)[]Proxies to mwc-list's items property.
indexMWCListIndex (readonly)****-1Proxies to mwc-list's index property.
selectedSelectedType (readonly)*****nullProxies to mwc-list's selected property.

* Corner is equivalent to type "TOP_LEFT"|"TOP_RIGHT"|"BOTTOM_LEFT"|"BOTTOM_RIGHT"|"TOP_START"|"TOP_END" |"BOTTOM_START"|"BOTTOM_END"

** Corner is equivalent to type "START"|"END"

*** DefaultFocusState is equivalent to type "NONE"|"LIST_ROOT"|"FIRST_ITEM"|"LAST_ITEM"

**** MWCListIndex is equivalent to type number|Set<number>.

***** SelectedType is equivaalent to type ListItemBase|ListItemBase[]|null. ListItemBase is the base class of mwc-list-item of which both mwc-check-list-item and mwc-radio-list-item also inherit from.

Methods

NameDescription
show() => voidSets open to true.
close() => voidSets open to false.
select(index: MWCMenuIndex) => voidSelects the elements at the given index / indices.
getFocusedItemIndex() => numberReturns the index of the currently-focused item. -1 if none are focused.
focusItemAtIndex(index) => voidFocuses the item at the given index and manages tabindex on all other items.
layout(updateItems = true) => voidResets tabindex on all items and will update items model if provided true. It may be required to call layout if selectability of an element is dynamically changed. e.g. [mwc-list-item] attribute is removed from a list item or noninteractive is dynamically set on a list item.

Events

Event NameTargetDetailDescription
openedmwc-menu-surfacenoneFired when opened.
closingmwc-menu-surfacenoneFired when closing but animation may not have completed yet. Use for time-sensitive logic that must be run immediately upon close.
closedmwc-menu-surfacenoneFired when closed.
actionmwc-listActionDetail*Fired when a selection has been made via click or keyboard aciton.
selectedmwc-listSelectedDetail*Fired when a selection has been made. index is the selected index (will be of type Set<number> if multi and number if single), and diff (of type IndexDiff**) represents the diff of added and removed indices from previous selection.

* See mwc-list's Events section for more details.

CSS Custom Properties

mwc-menu inherits from mwc-list, so all custom properties from mwc-list propagate through mwc-menu.

NameDefaultDescription
--mdc-menu-item-height48pxHeight of single-line list-items in the menu.
--mdc-menu-min-width112pxMenu min-width.
--mdc-menu-max-widthcalc(100vw - 32px)Menu max-width.
--mdc-menu-max-heightcalc(100vh - 32px)Menu max-height.
--mdc-menu-z-index8Z-index of the popup menu surface.

mwc-menu internally uses mwc-list, see the styling documentation for further details.

Global Custom Properties

This component exposes the following global theming custom properties.

NameDescription
--mdc-theme-surfaceColor of the menu surface.
--mdc-shape-mediumBorder radius of the dropdown.

Additional references

fundwave-fund-management@material/mwc-selectzagenzagen-productionplaytwo-core-cms-sectionsopenstamanager@everything-registry/sub-chunk-584open-scdkt-playground-elementsjupyter_pixanojvx-multiselectmwc-markdown-editormeteoalarm-card@tranbinh1998/wsm-web-component2@wces/dot-menu@wces/jsui-material@web-mjs/material-components@web-mjs/material-web-components@vonage/vwc-menu@vonage/vwc-surfaceapp-datepicker@aurodesignsystem/auro-datepicker@batchforce/core@backlight-dev/aodocs.aodocs-design-system@blackpurl/web-componentsplayground-elementsplayground-elements-ashruhil-uivve-breakoutvve-participantswc-range-datepickeryew-material-scriptsyido-elementsux-hub-entity-menuux-hub-product-cardshadow-prototypetaskana-workplace-libsaby-customizerscoped-material-components@chain-lib/cardano-components@cortexcloud/cortex-ui-legacycorgy-frontend@dotcms/dotcms-uicortex-ui-legacy@equinor/fusion-wc-menu@fortit/fwc-chip-list@fw-components/fw-avatar@holochain-open-dev/calendar-events@hydrofoil/shaperone-wc-material@hass-ada/frontend-lite@_lucky/app-datepicker@infinitebrahmanuniverse/nolb-_matedotcms-ui@dwane-vonage/vve-participants@esui/material-components@finastra/menu@jsview/material-components@klingen/location-search@leavittsoftware/leavittbook@leavittsoftware/titanium-address-input@leavittsoftware/leavitt-elements@leavittsoftware/leavitt-file-explorer@npm_lucky/app-datepicker@lordoftheflies/plutonium-styleshod-calendar-eventsholochain-playgroundhomeassistant-frontend-raceland@openenergytools/scl-wizarding
0.27.0

2 years ago

0.26.1

2 years ago

0.26.0

2 years ago

0.25.3

2 years ago

0.25.2

2 years ago

0.25.1

3 years ago

0.23.0

3 years ago

0.22.1

3 years ago

0.21.0

3 years ago

0.20.0

3 years ago

0.19.1

3 years ago

0.19.0

3 years ago

0.18.0

4 years ago

0.17.2

4 years ago

0.17.0

4 years ago

0.16.1

4 years ago

0.15.0

4 years ago

0.14.1

4 years ago

0.14.0

4 years ago

0.13.0

4 years ago