Skip to content
fuji-ui
Component

Command Menu

⌘K-style filterable, keyboard-navigable command palette.

Basic

Trigger with a shortcut hint

Kbd renders a single keyboard key/shortcut token - pair it with a visible trigger so the ⌘K chord is discoverable, not the only way in.

⌘K
  • items also accept a shortcut string, rendered next to each command's label inside the palette

When to use

  • App-wide quick navigation or actions triggered by a keyboard shortcut (⌘K) - jumping to pages, running commands, switching context.
  • A searchable list long enough that scanning isn't practical - filtering narrows it as the user types.

When not to use

  • A short, fixed action list tied to one trigger - a plain Dropdown Menu is lighter.
  • Primary navigation that should always be visible - this is a supplementary, opt-in shortcut, not a nav replacement.

Keyboard

KeyAction
TypeFilters items by label, group, and searchText (normalized: lowercase, punctuation collapsed).
ArrowUp / ArrowDownMoves the highlighted item across groups.
EnterRuns the highlighted item's onSelect and closes the menu.
EscapeCloses without running anything.

Mobile behavior

  • Opens the same way as desktop (via the trigger button; the ⌘K shortcut itself is a desktop-keyboard convenience), and the on-screen keyboard opens immediately since the input is focused on open.
  • The panel is width-clamped and vertically scrollable so a long, filtered result list doesn't overflow a short viewport.

Accessibility notes

  • Composed from Dialog under the hood, so it inherits focus trap, Escape-to-close, and focus-return-to-trigger for free.
  • Items are grouped visually by the group field; each group is exposed as its own labeled region for screen reader users.

Common mistakes

  • Wiring the ⌘K shortcut listener but forgetting to also expose a visible trigger button - keyboard-shortcut-only entry points are undiscoverable and inaccessible to users who can't use that chord.
  • Putting hundreds of items in one flat group - use group to organize a long list instead of one long unbroken scroll.

Known limitations

  • No built-in async/remote data loading - items must already be in memory; filter debouncing for a remote source is left to the consumer.

Related components

Dropdown MenuCombobox

CommandMenu props

open / onOpenChangeNone
boolean / (open: boolean) => void

Controlled open state - CommandMenu has no uncontrolled mode.

itemsNone
{ id, label, group?, icon?, shortcut?, searchText?, onSelect }[]

The full command list. Filtering, grouping, and highlighting are all handled internally.

placeholderNone
string

Search input placeholder.

CriterionStatusNote
Keyboard supportSupportedType-to-filter, arrow-key highlight across groups, Enter to run, Escape to close.
Focus managementSupportedInherits Dialog's focus trap and focus-return-to-trigger.
Screen reader labelsSupportedGrouped items are exposed as labeled regions.
Reduced motionSupportedprefers-reduced-motion: reduce zeroes all Fuji transition durations globally.
Reduced transparencySupportedprefers-reduced-transparency: reduce flattens Glass to opaque surfaces (portals included).
RTL layoutPartialLogical flex/grid gap works under dir="rtl"; directional chevrons are not yet mirrored.

API reference

openNone
boolean

Controlled open state of the command dialog.

onOpenChangeNone
(open: boolean) => void

Fires when the dialog opens or closes.

itemsNone
CommandMenuItem[]

Commands with label, group, icon, shortcut, and onSelect.

placeholder"Type a command or search…"
string

Search input placeholder.

classNameNone
string

Additional classes applied to the component root.