Menu button

Usage

Use a menu button to offer a short list of actions on one thing: a work order, a van, a table view. For choosing a value in a form, use a select or combobox; for navigation, use links (top nav, side nav) — never role="menu" for site navigation.

Keep menus to 3–9 items; group with separators and group labels. Put destructive items last, in red, and confirm them.
Item labels are verb-first and sentence case ("Print job sheet"). The trigger names the object or "Actions"; icon-only triggers name the item ("More actions for van KX-219").
Checkable items (menuitemcheckbox, menuitemradio) keep the menu open; plain actions close it.
One submenu level at most; deeper trees belong in a dialog or page.

Anatomy

Trigger — .btn or .icon-btn with aria-haspopup="menu", aria-expanded, aria-controls, commandfor/command="toggle-popover"
Surface — div.menu[popover][role=menu], anchored with CSS anchor positioning
Item — button.menu__item[role=menuitem|menuitemcheckbox|menuitemradio]
Leading icon / check — .menu__icon / .menu__check
Label — .menu__label
Shortcut or submenu chevron — kbd.menu__shortcut / .menu__chevron
Group + label, separator — .menu__group[role=group], .menu__group-label, hr.menu__separator

Examples

Live demos open real popovers (top layer, light dismiss, Esc — no JavaScript needed to open or close). js/menu.js adds roving focus, typeahead, submenu arrows and checkable items. Frozen previews are inert copies of the open surface. States marked hover, focus-visible and active are frozen with .is-hover, .is-focus-visible, .is-active. Those classes share their rule with the real pseudo-class, so what you see is exactly what users get. Never use them in product code.

Live: click, or focus and press ↓. Esc closes and returns focus.

Frozen preview of the open surface.

Shortcuts are hints; the real shortcuts work without opening the menu.

→ opens the submenu, ← closes it (mirrored in RTL).

Disabled items stay focusable so people can discover them; the reason goes next to the trigger: "Log at least one task before closing".

<button type="button" class="btn btn--secondary" id="wo-actions-btn"
        aria-haspopup="menu" aria-expanded="false" aria-controls="wo-actions"
        commandfor="wo-actions" command="toggle-popover" style="anchor-name:--wo-actions">
  <span class="btn__label">Actions</span>
  <svg class="menu-trigger__chevron" aria-hidden="true" focusable="false"><use href="#icon-chevron-down"></use></svg>
</button>
<div class="menu" id="wo-actions" popover role="menu" aria-labelledby="wo-actions-btn" style="position-anchor:--wo-actions">
  <button type="button" class="menu__item" role="menuitem">
    <svg class="menu__icon" aria-hidden="true" focusable="false"><use href="#icon-pencil"></use></svg>
    <span class="menu__label">Edit work order</span>
    <kbd class="menu__shortcut">E</kbd>
  </button>
  <hr class="menu__separator" role="separator">
  <div class="menu__group" role="group" aria-labelledby="sort-label">
    <div class="menu__group-label" id="sort-label">Sort by</div>
    <button type="button" class="menu__item" role="menuitemradio" aria-checked="true">
      <svg class="menu__check" aria-hidden="true" focusable="false"><use href="#icon-check"></use></svg>
      <span class="menu__label">Due date</span>
    </button>
  </div>
  <!-- Submenu: trigger is a menuitem, the sub-popover is a child of this menu -->
  <button type="button" class="menu__item" role="menuitem" id="move-btn" aria-haspopup="menu" aria-expanded="false"
          aria-controls="move" commandfor="move" command="toggle-popover" style="anchor-name:--move">…</button>
  <div class="menu menu--sub" id="move" popover role="menu" aria-labelledby="move-btn" style="position-anchor:--move">…</div>
  <button type="button" class="menu__item menu__item--danger" role="menuitem">…Delete work order</button>
</div>

<script type="module">import { init } from "./js/menu.js"; init();</script>

API

Hook	Values	Purpose
`.menu`	block class	Popover surface; `role="menu"`
`.menu--sub`	modifier	Submenu, opens inline-end
`.menu--static`	docs-only modifier	In-flow preview of an open menu
`.menu__item`, `.menu__item--danger`	part / modifier	Item, destructive item
`.menu__icon \| __check \| __label \| __shortcut \| __chevron`	part	Item content
`.menu__group`, `.menu__group-label`, `.menu__separator`	part	Grouping
`.menu-trigger__chevron`	part (trigger)	Rotates when `aria-expanded="true"`
`aria-checked`	attribute	Checkable item state
`aria-disabled="true"`	attribute	Unavailable, still focusable
`menu-select`	event	Fired on the item: `detail { item, value, checked }`
`init(root)`	JS (js/menu.js)	Enhances every `[aria-haspopup=menu][aria-controls]`

Do and don't

Do group related actions and put destructive ones last.

Don't use a menu for site navigation — use links in a nav.

Keyboard interaction
Key	Behavior
`Enter` / `Space` / `↓` (trigger)	Opens and focuses the first item
`↑` (trigger)	Opens and focuses the last item
`↓` / `↑`	Next / previous item (wraps)
`Home` / `End`	First / last item
Letter keys	Typeahead to the next item starting with those letters
`Enter` / `Space` (item)	Runs the action and closes; toggles checkable items
`→` / `←`	Open / close a submenu (mirrored in RTL)
`Esc`	Closes the current level; focus returns to its trigger
`Tab`	Closes the whole menu and moves on

Pattern: WAI-ARIA APG Menu Button. The trigger's aria-expanded is kept in sync on every open and close.
Disabled items use aria-disabled="true", stay reachable with arrows, and do nothing when activated.
Checked state: a check icon plus aria-checked — never color alone.
Placement: CSS anchor positioning with the shared try set (--flip-block, --flip-inline); without anchor support it opens centered in the top layer, still usable.
Fallback: browsers without invoker commands get togglePopover() on click from js/menu.js.

Tokens

Custom property	Purpose
`--color-elevation-surface-overlay`, `--overlay-radius`, `--overlay-shadow`	Surface
`--z-dropdown`	Stacking (top layer when open as a popover)
`--size-control-md \| -sm`	Item height (comfortable / compact)
`--color-action-ghost-bg-hover`	Highlighted item
`--color-feedback-danger-fg \| -bg`	Destructive item
`--color-text-disabled`	Disabled item
`--color-selected-fg`	Check mark
`--motion-duration-fast`, `--motion-easing-enter`	Open animation (skipped with reduced motion)

Menu button

Usage

Anatomy

Examples

Menu button

API

Do and don't

Accessibility

Tokens