Prepared Docs

Overview

A menu surfaces a set of actions or choices from a trigger until dismissed. Items can be plain, check, or radio; separators and labels organize related groups; navigable variants add search and nested panes for longer lists. The mental model is "reveal, scan, act"—compact power without navigating away from the current context.

Actions

Flag for QA

Transfer to supervisor

Delete note

When to use

Secondary actions that would clutter a toolbar if always visible.
Scoped options tied to a row, card, or current selection.
Single- or multi-select lists that are not full forms (check or radio items inside the menu).
Hierarchical settings where shallow nesting keeps related items together.
Toolbar overflow, row actions, or anchored chrome where NavigableMenu, MenuItemCheckbox, and optional search carry multi-select—menu-dismissal and focus return should match menu patterns, not standalone fields.

Searchable checklists vs Combobox multi-select

For search + multiple selections, compare to Combobox with multiSelect. Use NavigableMenu with searchable and MenuItemCheckbox when the trigger is contextual (toolbar overflow, row/card “⋯”), the panel mixes actions, radios, switches, separators, or submenus, or there is no labeled field and no need for pills summarizing selection when closed. Use Combobox multiSelect for a filter or form row with a flat options list, keywords, and chips on the trigger.

When not to use

Primary workflow actions that should stay visible—use Button or SplitButton.
Long forms or rich content—use a Drawer or Modal.
Site-wide navigation—use sidebar or nav components.
Labeled multi-select form fields with pills and flat options—use Combobox multiSelect instead of a transient menu.
Touch-first mobile flows where sheets or full-width pickers scan more clearly.

Searchable checklist vs Combobox multi-select

Use NavigableMenu with searchable, MenuItemCheckbox, or grouped check workflows when operators pick multiple values inside an action menu—toolbar overflow, row menus, contextual filters anchored to chrome. Keyboard and ARIA expectations stay menu-first (see Keyboard support and NavigableMenu).

Use Combobox with multiSelect when the UI is a labeled form field: flat options, a wrapping chips field with dismissible pills (and automatic +N more overflow), and option rows toggled without closing. That pattern submits with surrounding form state rather than behaving like a transient overlay menu.

Trigger variants

Dropdown trigger. Default labeled opener. The label should predict the menu contents.
Button trigger. Summarize the set in the label ("Export", not "Menu").
Icon button trigger. For dense chrome. Pair with a tooltip only when the icon meaning is not obvious on its own.
Navigable + search. Use when item count approaches ten or the structure is multi-level; always include an empty state for zero results.

Content guidelines

Verb-led labels on action items ("Assign…", "Open in new tab"); parallel grammar per section.
Destructive items sit in their own section with destructive styling and a confirmation step for irreversible work.
Prefer disabling with an explanation (tooltip or helper context) over silent removal when operators might look for the action.
Search placeholder should say what can be searched ("Search by name or ID").

Reordering items

Use sortable on Menu or NavigableMenu when operators need to persist a custom item order (for example reordering table columns in a filter menu). Give each MenuItem or MenuItemCheckbox a stable sortableId and update your backing list from onReorder. Drag from the handle or the row; keyboard users can grab with Space or Enter, move with Arrow Up/Down, drop with Space or Enter, and cancel with Escape. Checkbox rows drag from the handle only, so activating the row—by click or Space/Enter—still toggles its checked state.

Behavior and states

Open and close. Escape dismisses; outside click dismisses unless a modal pattern overrides.
Viewport bounds. Menu content stays inside the collision boundary (the viewport by default). Width is capped to Radix available width, and content uses a small collision padding so End-aligned menus near a panel or window edge shift inward instead of painting off-screen.
Panel width while scrolling. When content exceeds the 40vh max height, root menu panels apply a --overflow modifier that reserves space for a vertical scrollbar (scrollbar-gutter: stable with a narrow themed track). Short menus that fit within the panel do not show an empty gutter. While scrolling, the panel does not widen or shift horizontally.
Focus. Initial focus lands on the first item; focus returns to the trigger on close.
Radio and check items. Reflect server truth after async actions—don't leave a local-only toggle that re-renders stale on refresh.
Async actions. Show pending state on the item or block repeat clicks.

Best practices

Order by frequency; put safest reversible actions near the top of casual menus.
Size width for the longest label so translated strings don't clip.
Debounce search in large dynamic lists.

Don't

Hide the only recovery path behind a deep submenu.
Mix unrelated domains in one menu without labels between groups.
Use icons without text unless the team has standardized those icons system-wide.

Accessibility

Items are reachable by keyboard with arrow navigation; items expose names and group context; the trigger reflects aria-expanded. See Accessibility for the full contract.

Sortable drag handles are pointer-only and do not take focus away from the menu item row. Cancelling a keyboard reorder restores the original order without emitting a second committed reorder.

Sortable status messages use a visually hidden polite live region so reorder updates are announced without adding visible menu content.

Pointer reordering clears click suppression when a gesture is cancelled or dropped outside the menu. Edge auto-scroll uses elapsed frame time, so its speed remains consistent on high-refresh displays.

While an item is grabbed from the keyboard, Tab commits the current order and continues normal focus movement out of the menu.

Interaction tests should drive sortable controls through user-level pointer and keyboard events so focus, cancellation, and browser defaults remain covered.

The sortable menu examples cover whole-row and handle-only dragging, plus idle, top, and bottom drop previews.

Use Shift+Space or Shift+Enter on a focused sortable row to begin keyboard reordering; unmodified Space and Enter keep their normal item activation behavior. Assign a unique sortableId whenever labels can repeat; sorting is disabled when identifiers collide. Checkbox items without a controlled checked value retain their alternating selection state.

Combobox for field-shaped searchable single- or multiSelect picking (not contextual action menus).
Context menu for right-click menus on a specific target.
Combobox for searchable single- or multi-select fields (multiSelect + options).
Icon button for dense triggers.
Modal for actions that require confirmation or extra fields.

Loading Indicator / Accessibility

Menu / API and Development

Overview

When to use

Searchable checklists vs Combobox multi-select

When not to use

Searchable checklist vs Combobox multi-select

Overview

Actions

Flag for QA

Transfer to supervisor

Delete note

When to use

Secondary actions that would clutter a toolbar if always visible.
Scoped options tied to a row, card, or current selection.
Single- or multi-select lists that are not full forms (check or radio items inside the menu).
Hierarchical settings where shallow nesting keeps related items together.
Toolbar overflow, row actions, or anchored chrome where NavigableMenu, MenuItemCheckbox, and optional search carry multi-select—menu-dismissal and focus return should match menu patterns, not standalone fields.

Searchable checklists vs Combobox multi-select

When not to use

Primary workflow actions that should stay visible—use Button or SplitButton.
Long forms or rich content—use a Drawer or Modal.
Site-wide navigation—use sidebar or nav components.
Labeled multi-select form fields with pills and flat options—use Combobox multiSelect instead of a transient menu.
Touch-first mobile flows where sheets or full-width pickers scan more clearly.

Searchable checklist vs Combobox multi-select

Trigger variants

Dropdown trigger. Default labeled opener. The label should predict the menu contents.
Button trigger. Summarize the set in the label ("Export", not "Menu").
Icon button trigger. For dense chrome. Pair with a tooltip only when the icon meaning is not obvious on its own.
Navigable + search. Use when item count approaches ten or the structure is multi-level; always include an empty state for zero results.

Content guidelines

Verb-led labels on action items ("Assign…", "Open in new tab"); parallel grammar per section.
Destructive items sit in their own section with destructive styling and a confirmation step for irreversible work.
Prefer disabling with an explanation (tooltip or helper context) over silent removal when operators might look for the action.
Search placeholder should say what can be searched ("Search by name or ID").

Reordering items

Behavior and states

Open and close. Escape dismisses; outside click dismisses unless a modal pattern overrides.
Viewport bounds. Menu content stays inside the collision boundary (the viewport by default). Width is capped to Radix available width, and content uses a small collision padding so End-aligned menus near a panel or window edge shift inward instead of painting off-screen.
Panel width while scrolling. When content exceeds the 40vh max height, root menu panels apply a --overflow modifier that reserves space for a vertical scrollbar (scrollbar-gutter: stable with a narrow themed track). Short menus that fit within the panel do not show an empty gutter. While scrolling, the panel does not widen or shift horizontally.
Focus. Initial focus lands on the first item; focus returns to the trigger on close.
Radio and check items. Reflect server truth after async actions—don't leave a local-only toggle that re-renders stale on refresh.
Async actions. Show pending state on the item or block repeat clicks.

Best practices

Order by frequency; put safest reversible actions near the top of casual menus.
Size width for the longest label so translated strings don't clip.
Debounce search in large dynamic lists.

Don't

Hide the only recovery path behind a deep submenu.
Mix unrelated domains in one menu without labels between groups.
Use icons without text unless the team has standardized those icons system-wide.

Accessibility

Items are reachable by keyboard with arrow navigation; items expose names and group context; the trigger reflects aria-expanded. See Accessibility for the full contract.

Sortable drag handles are pointer-only and do not take focus away from the menu item row. Cancelling a keyboard reorder restores the original order without emitting a second committed reorder.

Sortable status messages use a visually hidden polite live region so reorder updates are announced without adding visible menu content.

While an item is grabbed from the keyboard, Tab commits the current order and continues normal focus movement out of the menu.

Interaction tests should drive sortable controls through user-level pointer and keyboard events so focus, cancellation, and browser defaults remain covered.

The sortable menu examples cover whole-row and handle-only dragging, plus idle, top, and bottom drop previews.

Combobox for field-shaped searchable single- or multiSelect picking (not contextual action menus).
Context menu for right-click menus on a specific target.
Combobox for searchable single- or multi-select fields (multiSelect + options).
Icon button for dense triggers.
Modal for actions that require confirmation or extra fields.

Loading Indicator / Accessibility

Menu / API and Development

Overview

When to use

Searchable checklists vs Combobox multi-select

When not to use

Searchable checklist vs Combobox multi-select