@dev.mohe/mwc-menu

v0.19.3

Published

2 years ago

Material Design menu web component

Downloads

0High
0Medium
0Low

dev.mohe

material design web components menu

`<mwc-menu>`

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 @dev.mohe/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 '@dev.mohe/mwc-menu';
  import '@dev.mohe/mwc-list/mwc-list-item';

  // 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 '@dev.mohe/mwc-menu';
  import '@dev.mohe/mwc-list/mwc-list-item';

  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

| Name | Description | ----------------- | ------------- | default | Content 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

Name --------------------- open anchor corner menuCorner quick absolute fixed x y forceGroupSelection defaultFocus fullwidth wrapFocus innerRole multi activatable items index selected | Type | Default | Description | --------------------------------- | ------------- | ----------- | boolean | false | Whether the menu should open and display. | HTMLElement\|null | null | Determines 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. | Corner* | "TOP_START" | Corner of the anchor from which the menu should position itself. | MenuCorner** | "START" | Horizontal corner of the menu from which the menu should position itself. NOTE: Only horizontal corners are supported. | boolean | false | Whether to skip the opening animation. | boolean | false | Makes 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. | boolean | false | Makes 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. | number\|null | null | Sets horizontal position when absolute or fixed. When given an anchor, sets horizontal position relative to anchor at given corner. Requires y not to be null. | number\|null | null | Sets vertical position when absolute or fixed. When given an anchor, sets vertical position relative to anchor at given corner. Requires x not to be null. | boolean | false | Forces a menu group to have a selected item by preventing deselection of menu items in menu groups via user interaction. | DefaultFocusState*** | "LIST_ROOT" | Item to focus upon menu open. | boolean | false | Sets surface width to 100%. | boolean | false | Proxies to mwc-list's wrapFocus property. | "menu" | "listbox" | "menu" | boolean | false | Proxies to mwc-list's multi property. | boolean | false | Proxies to mwc-list's activatable property. | ListItemBase[] (readonly) | [] | Proxies to mwc-list's items property. | MWCListIndex (readonly)**** | -1 | Proxies to mwc-list's index property. | SelectedType (readonly)***** | null | Proxies to mwc-list's selected property.

** 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

| Name | Description | -------- | ------------- | show() => void | Sets open to false. | close() => void | Sets open to true. | select(index: MWCMenuIndex) => void | Selects the elements at the given index / indices. | getFocusedItemIndex() => number | Returns the index of the currently-focused item. -1 if none are focused. | focusItemAtIndex(index) => void | Focuses the item at the given index and manages tabindex on all other items. | layout(updateItems = true) => void | Resets 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 Name | Target | Detail | Description | ---------- | ------------------ | ------------------ | ----------- | opened | mwc-menu-surface | none | Fired when opened. | closed | mwc-menu-surface | none | Fired when closed. | action | mwc-list | ActionDetail* | Fired when a selection has been made via click or keyboard aciton. | selected | mwc-list | SelectedDetail* | 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.

| Name | Default | Description | ------------------------ | ------- |------------ | --mdc-menu-item-height | 48px | Height of single-line list-items in the menu. | --mdc-menu-min-width | auto | Menu min-width. | --mdc-menu-max-width | auto | Menu max-width. | --mdc-menu-max-height | calc(100vh - 32px) and content height | Menu max height. | --mdc-menu-z-index | 8 | Z-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.

| Name | Description | ------------------------------------ | ----------- | --mdc-theme-surface | Color of the menu surface. | --mdc-shape-medium | Border radius of the dropdown.

Additional references

MDC Web menus