## Overview An `` is used for creating a menu list. The various elements inside a menu are given as [``](../menu-group), [``](../menu-item), or ``. Often a `` element will appear in a [``](../popover) element so that it displays as a toggling menu. ### Usage [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/menu?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/menu) [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/menu?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/menu) [![Try it on Stackblitz](https://img.shields.io/badge/Try%20it%20on-Stackblitz-blue?style=for-the-badge)](https://stackblitz.com/edit/vitejs-vite-ascdqv3p) ``` yarn add @spectrum-web-components/menu ``` Import the side effectful registration of ``, ``, ``, or `` individually as follows: ``` import '@spectrum-web-components/menu/sp-menu.js'; import '@spectrum-web-components/menu/sp-menu-group.js'; import '@spectrum-web-components/menu/sp-menu-item.js'; import '@spectrum-web-components/menu/sp-menu-divider.js'; ``` When looking to leverage the `Menu`, `MenuGroup`, `MenuItem`, or `MenuDivider` base classes as a type and/or for extension purposes, do so via: ``` import { Menu, MenuGroup, MenuItem, MenuDivider } from '@spectrum-web-components/menu'; ``` ### Anatomy ```html Deselect Select inverse Feather... Select and mask... Save selection Make work path ``` #### Popover menus Often an `` element will be delivered inside of an `` element when displaying it above other content. ```html Deselect Select inverse Feather... Select and mask... Save selection Make work path ``` #### Labels To render accessibly, an `` element or its parent `` must have a label. For an accessible label that is visibly hidden, but can still be read by assistive technology, use the `label` attribute. Menu with label ```html demo Deselect Select inverse Feather... Select and mask... Save selection Make work path ``` Popover with label ```html demo Deselect Select inverse Feather... Select and mask... Save selection Make work path ``` ### Options #### Sizes Small ```html demo Deselect Select inverse Feather... Select and mask... Save selection Make work path Deselect Select inverse Feather... Select and mask... Save selection Make work path ``` Medium ```html demo Deselect Select inverse Feather... Select and mask... Save selection Make work path Deselect Select inverse Feather... Select and mask... Save selection Make work path ``` Large ```html demo Deselect Select inverse Feather... Select and mask... Save selection Make work path Deselect Select inverse Feather... Select and mask... Save selection Make work path ``` Extra Large ```html demo Deselect Select inverse Feather... Select and mask... Save selection Make work path Deselect Select inverse Feather... Select and mask... Save selection Make work path ``` #### Selection The `` element can be instructed to maintain a selection via the `selects` attribute. Depending on the chosen algorithm, the `` element will hold a `value` property and manage the `selected` state of its `` descendants. - When `selects="single"`, the `` element will maintain one selected item after an initial selection is made. - When `selects` is set to `multiple`, the `` element will maintain zero or more selected items. - When `selects` is set to `inherit`, the `` element will allow its `` children to participate in the selection of its nearest `` ancestor. Single ```html demo

The value of the `<sp-menu>` element is:

Square Triangle Parallelogram Star Hexagon Circle ``` Multiple ```html demo

The value of the `<sp-menu>` element is: item-3,item-4

Apple Banana Goji berry Grapes Kumquat Orange ``` Inherit ```html demo

The value of the `<sp-menu>` element is: item-3 || item-4 || item-8 || item-11

Apple Banana Goji berry Grapes Kumquat Orange Carrot Garlic Lettuce Onion Potato Tomato ``` ### Behaviors #### "change" event Regardless of whether or not `` carries a selection, when one of the `` children that it manages is activated, the `` element will dispatch a `change` event. At dispatch time, even when a selection is not held due to the absence of the `selects` attribute, the `value` of the `` will correspond to the `` that was activated. When the `selects` attribute is present, this `value` will persist beyond the lifecycle of the `change` event. When `selects="multiple"`, the values of multiple items will be comma separated, unless otherwise set via the `value-separator` attribute. Note: The `change` event is only dispatched on a left mouse click or Enter/Space keypress. Right/Middle mouse clicks will not dispatch the `change` event. ### Accessibility Review the accessibility guidelines for the [menu-item](../menu-item#accessibility-guidelines) and [menu-group](../menu-group#accessibility-guidelines) descendants. #### Include a label A menu is required to have an accessible label.