# Menus Menus show a temporary set of actions or choices, opened from a button, a text field or a context. **Example: A button that opens a menu of file actions** ```html File New Open Save ``` ## Usage guidelines * **Use it for temporary actions.** A menu shows a short set of actions on demand. To show actions on screen at all times, use a [toolbar](/material-web/3.0/components/toolbar/). * **Open it from many places.** A menu can open from a button, an icon button, a split button or a text field, or as a [context menu](#context-menu). * **Organize long menus.** Use [groups](#groups) with labels and dividers to separate related choices. * **Choose a color.** The `standard` color suits most menus; `vibrant` makes the selected items stand out. ## Anatomy A menu holds items, groups and dividers. An item holds a label and optional slots, including a submenu. **Example: A menu with a group, an item with all of its slots, a divider and another item** *HTML* ```html More share Share Send a link Ctrl+S chevron_right Email Messages Delete ``` *TypeScript* ```ts const menu = document.querySelector('#more-menu')!; menu.showPopover({source: document.querySelector('#more')!}); ``` ## Examples ### Opening a menu A menu is a popover. Point an `md-gb-button` (or `md-gb-icon-button`, or a native button) at it with `popovertarget`, or call `showPopover()` from script. The menu positions itself next to the button and closes on Escape, when focus leaves, or when an item is chosen. **Example: A button that opens a menu of sort options** ```html Sort Name Date modified Size ``` ### Icons and supporting text Fill the `leading`, `supporting-text`, `trailing-text` and `trailing` slots to add detail to an item. **Example: Menu items with leading icons and keyboard shortcuts** ```html Edit content_cut Cut Ctrl+X content_copy Copy Ctrl+C content_paste Paste Ctrl+V ``` ### Groups Wrap related items in an `md-gb-menu-group`. Set `label` for a heading, and `checkable` to `single` or `multiple` to make the items selectable like radio buttons or checkboxes. Use `checked` on the selected items. **Example: A menu with a single-select group and a multi-select group** ```html View Name Date modified Hidden files File extensions ``` ### Grouped layout Set `layout="grouped"` to show each group on its own surface with a gap between them, instead of one surface with dividers. **Example: A menu with two groups on separate surfaces** ```html Actions Undo Redo Cut Copy Paste ``` ### Vibrant color Set `color="vibrant"` to use the tertiary color roles instead of the surface-based `standard` style. **Example: A vibrant menu with a checked item** ```html Theme System Light Dark ``` ### Submenus Put an `md-gb-menu` in an item's `submenu` slot. It opens beside the item on click, Enter, Space or the Right arrow key (Left in right-to-left layouts). **Example: A menu item that opens a submenu** ```html Share Copy link Send to Email Message ``` ### Context menu Set `context-for` to the id of an element to open the menu on a secondary click, the context menu key or a long press. **Example: A menu that opens on right-click** ```html
Right-click or long press this photo
Open in new window Save as Copy link ``` ### Density Set `density` from `0` (default) down to `-3` to remove 4px of height per item for each step. Submenus inherit it. Keep it off by default and let people opt in. **Example: A menu at density -2** ```html Open Rename Duplicate Delete ``` ## Accessibility * The menu has `role="menu"`, and items have `role="menuitem"`, or `menuitemradio` and `menuitemcheckbox` in checkable groups. * On the button that opens the menu, Up and Down open it and focus the first item; Enter and Space open it natively. * In an open menu, Up and Down move between items (disabled items included), Home and End go to the first and last item, and typing a letter jumps to the next item that starts with it. * Escape and Tab close the menu and return focus to the button. Left (Right in right-to-left layouts) closes a submenu. * Give a menu that has no clear visible title an `aria-label`. ## API reference ### <md-gb-menu> A Material Design component. #### Properties | Property | Attribute | Type | Default | | --- | --- | --- | --- | | color
The color style: standard (surface-based) or vibrant (tertiary). | color | MenuColor | MENU_COLORS.standard | | contextFor
The id of an element (in the same root) that opens this menu as a context menu on a secondary click, the context menu key or a long press (menus.md "Context menus ... usually open with a secondary click"; "Performs a specific action to trigger the menu, like right-click or press-and-hold"). | context-for | string | '' | | density
The density, from 0 (default) to -3 (menus.md "Density": "On web only, density levels control the spacing between elements. Increasing density decreases the top and bottom padding"). Each step removes 4px from the items' height; submenus inherit it. Values are clamped to that range. Dense items are smaller than the 48px recommended target, so don't apply density by default; let people opt in (grids-spacing.md "Avoid applying component scaling by default"). | density | Density | | | filterFor
The id of a text field (in the same root) the menu is attached to. As the person types in it, the menu opens (without taking focus) and shows only the items whose label contains the text, case-insensitively (menus.md "Filtering": "As someone types, the list of menu options filters to show relevant results"). The remaining items ease into their new position ("Menu items ease into their new position as the menu is filtered"), unless motion is reduced. Fires filter with the query. | filter-for | string | '' | | layout
The layout: standard items on one surface, or grouped md-gb-menu-groups on separate surfaces with gaps between them. | layout | MenuLayout | 'standard' | #### Slots | Slot | Description | | --- | --- | | default | The menu's items, groups and dividers. | #### Methods | Method | Description | | --- | --- | | closeAll
() => void | Closes this menu and every menu it is a submenu of. | | filter
(query: string) => void | Shows only the items whose label contains query, easing the others into their new position. | | showAt
(x: number, y: number) => void | Opens the menu at a point in the viewport (a context menu), keeping it inside the window: it opens below and after the point, and flips when there is no room. | #### CSS parts | Part | Description | | --- | --- | | ::part(menu) | The menu's root element. | #### CSS custom properties | Property | Description | | --- | --- | | --container-color | | | --container-elevation | | | --container-max-width | | | --container-min-width | | | --container-shape | | | --density-step | Item height removed per density step (set on the items). | | --gap | Space between groups in the grouped layout. | | --group-padding | | | --group-shape | | | --section-label-text | | | --section-label-text-color | | ### <md-gb-menu-group> A Material Design component. #### Properties | Property | Attribute | Type | Default | | --- | --- | --- | --- | | checkable | checkable | MenuItemCheckable | null | | label
The section label shown above the group's items. | label | string | '' | #### Slots | Slot | Description | | --- | --- | | default | Used to display the menu group's items. | #### CSS parts | Part | Description | | --- | --- | | ::part(group) | The group's root element. | | ::part(label) | The section label. | ### <md-gb-menu-item> A Material Design component. #### Properties | Property | Attribute | Type | Default | | --- | --- | --- | --- | | checked | checked | boolean | false | | disabled | disabled | boolean | false | #### Slots | Slot | Description | | --- | --- | | default | Used to display the item's primary label. | | leading | Used to display icons and content before the item's main content. | | submenu | An md-gb-menu to open as this item's submenu. | | supporting-text | Used to display supporting text below the main label. | | trailing | Used to display icons and content after the item's main content. | | trailing-text | Used to display metadata or text after the item's main content. | #### Events | Event | Description | | --- | --- | | change
Event | Fired when a checkbox or menu item is checked or unchecked. | | input
InputEvent | Fired when a checkbox or menu item is checked or unchecked. | #### Methods | Method | Description | | --- | --- | | closeSubmenu
() => void | Closes the item's submenu. | | openSubmenu
(focus?: boolean) => void | Opens the item's submenu next to it and focuses its first item. | #### CSS parts | Part | Description | | --- | --- | | ::part(menu-item) | The menu item's root element. | #### CSS custom properties | Property | Description | | --- | --- | | --between-space | | | --bottom-space | | | --container-color | | | --height | | | --inner-corner-corner-size | | | --label-text | | | --label-text-axes | | | --label-text-color | | | --label-text-tracking | | | --leading-icon-color | | | --leading-icon-size | | | --leading-space | | | --shape | | | --supporting-text | | | --supporting-text-axes | | | --supporting-text-color | | | --supporting-text-tracking | | | --top-space | | | --trailing-icon-color | | | --trailing-icon-size | | | --trailing-space | | | --trailing-supporting-text | | | --trailing-supporting-text-axes | | | --trailing-supporting-text-color | | | --trailing-supporting-text-tracking | |