import { Canvas, Meta, Controls } from '@storybook/blocks' import { ResourceLinks, KAIOInstallation, DosAndDonts, DoOrDont } from '~storybook/components' import * as MenuDocsStories from './Menu.docs.stories' import * as MenuStories from './Menu.stories' # Menu Updated July 6, 2024 ## Overview A menu displays a list of actions in a popover, toggled opened with a button. Save Edit Delete `, }} /> ### Anatomy - A Menu is made up of: - A trigger button - A popover - A list of menu items - Menu items may be organised into sections, with a heading for each section. - The menu trigger button, which may be any variation of a button. ### When to use - When you have a group of related actions for a page or item on the page. - The actions either: - Cause an action on the page (e.g. delete), or - Navigate somewhere ### When not to use - When you want to persist a user selection. - Use a Select/Multi-Select or Combobox/Multi-Combobox component instead. - When you want additional elements beyond a list of menu items (e.g. a search input) - Use a Modal, or construct your own pattern with a Popover. - It's recommended that you avoid this because of the complexity it adds for accessibility. - Inside a navigation bar - Different DOM elements and behaviour is required for a dropdown menu in a navigation bar. ### Specs #### Do use a menu for an overflow of actions Menus work well as an overflow for a list of actions on a page or section. Try to avoid using menus for a single action, favouring an inline button/link instead. #### Don't use Menus to persist a user selection Menus are not intended for a list of options where a user selection persists. Use a Select/Multi-Select or Combobox/Multi-Combobox component instead. #### Do use a chevron icon when using a text label Providing this icon is an important part of visually communicating that the button triggers a menu. #### Do give the trigger button a concise and unique label The label of the trigger button will be important for screen reader users to understand the purpose of the menu. Menu button labels are often too generic and need context added. E.g. a label of “Actions” is too generic if you have multiple menus on a single page. Avoid using the words “Open/close” or “Menu” in the label, both of these things are communicated to screen reader users already with ARIA properties. The following examples show you the verbose labels. In practice you will either want to use visually hidden text (when using a text-based trigger button), or an aria-label (when using an icon-based trigger button) to create the label. #### Do use icons in menu items for common actions Icons beside items make sense for common actions (pencil for edit, trash can for delete, etc). Avoid using icons when: - The action is unique and doesn't have a commonly known icon associated. - Not all menu items will have an icon - You will have duplicates of icons in the list #### Don't repeat the same word in the menu item labels Context may be useful in some cases, but avoid adding context if it will be repeated in every menu item label. #### Do use sentence case for menu items Write menu items in sentence case unless they contain words that are branded terms. #### Don't use elipses in menu items Avoid using ellipses (…) in menu item names within products whenever possible. An ellipsis often implies that the action for a menu item will open in a new view, or that a user will be taken elsewhere.