Skip to content

Menu

C-07 · Components · Overlays

All elements · Menu on the Components page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for Menu.

Guidance

When to use

  • Use a menu to list actions for an item, such as Open, Download, Share and Delete, behind one button.
  • Use a menu for a row's or a selection's context actions in dense views.
  • Use menuitemcheckbox for on and off options and menuitemradio for one choice from a set, such as review markup modes.
  • Use the office menu parts (__check, __description, __icon-row, submenus) for editor menus.

When to consider something else

  • If the user picks a value for a field, use a select; its listbox is styled like a menu but has value semantics. See Select.
  • If the content is information or a small form, use a popover. See Popover.
  • If there are only two or three actions and there is room, show them as buttons. See Button.
  • If a toolbar runs out of space, move its extra commands into an overflow menu. See Overflow.

Usability

Do
  • Group items with .qf-menu__section headers and dividers; put destructive items last.
  • Show keyboard shortcuts in __shortcut so users can learn them.
  • End labels that open a dialog with an ellipsis, such as "Share…".
  • Keep disabled items visible so the menu does not change shape.
Don’t
  • Don't use a menu for navigation between pages.
  • Don't nest submenus more than one level.
  • Don't rely on the red data-tone="danger" color alone; the label must say what happens.

Accessibility

Keyboard

Menu keyboard
Keys Action
Enter or Space On the trigger, opens the menu.
Arrow Down or Arrow Up On the trigger, opens the menu and focuses the first or last item. In the menu, moves to the next or previous item, wrapping.
Home or End Moves to the first or last item.
Enter or Space On an item, runs it and closes the menu; a menuitemcheckbox flips its state and stays open.
Escape Closes the menu and returns focus to the trigger.
Arrow Right or Arrow Left On an item with a submenu, the binding must open it and focus its first item, and close it back to the parent item.
Shift+F10 or Context Menu key For a context menu, opens it on the focused row (wired for nav rows).

Roles and names

  • The container is role="menu" with a name (aria-label or the trigger's label); items are menuitem, menuitemcheckbox or menuitemradio with aria-checked.
  • The trigger has aria-haspopup="menu", aria-expanded and aria-controls.
  • Disabled items use aria-disabled="true" and are skipped by the arrow keys.
  • A submenu item has aria-haspopup="menu" and aria-expanded; the office icon row is a role="group" with a name, and each icon item has aria-label.

Focus

  • Focus moves into the menu with roving tabindex (one item at 0); data-state="active" marks the virtual focus when focus stays on a combobox.
  • Tab does not move between items; the binding must close the menu on Tab and let focus continue in page order.
  • When the menu closes with focus inside it, focus returns to the trigger.

Other requirements

  • Items are 36px high, 28px with data-dense, which meets 2.5.8.
  • Checked state shows a check mark and a fill, not color alone (1.4.1).
  • The a11y report lists the shortcut text on the danger item as dark-theme contrast debt (1.4.3).
  • Typeahead by first letter is not in the static layer; the binding should add it for long menus.

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

Menu test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order. (7 rows)
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (4 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- menu --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

Menu package
Source css/classic/components/overlays.css
Specimens also use Box · Button · Card · Chip · Divider · Icon · Table · Text · Toolbar
Sprites sprites/icons.svg · sprites/office-icons.svg
React Not yet available: the React binding has not started.

Latest updates

Menu latest updates
Date Version Breaking Description
2026-10-02 0.1 No Extend Tooltip, Menu, Select, Tabs and Toolbar for office surfaces

All release notes