Command Palette
A searchable list of commands and pages in a dialog, opened with a click or a keyboard shortcut.
Usage
CommandPalette is a Dialog with an Autocomplete inside it, built on Base UI's Dialog and Autocomplete. Typing filters the list, the first match is always highlighted, and Enter runs it:
CommandPalette- the root. Holds the open state and the data: passitems(flat, or grouped as{ value, items }) and, for object items, alabelor anitemToStringValuethe filter can read.shortcutadds a ⌘ or Ctrl key combination that opens and closes it.CommandPaletteTrigger- an optional button that opens the palette. Project it onto your ownButtonwithrender.CommandPaletteContent- the portalled dialog, near the top of the screen. It takes the Dialog'sbackdropandframe, and the samebackdropProps,viewportPropsandportalPropsescape hatches.CommandPaletteInput- the search field, styled likeInput. It takes focus when the palette opens.CommandPaletteList- the scrollable list. Pass a render function over the filtered items.CommandPaletteItem- one command. Run it fromonClick, which also fires on Enter, or make it a link withrender={<a href="…" />}. It closes the palette unlesscloseOnSelect={false}.CommandPaletteEmpty- shown only when nothing matches.CommandPaletteGroup,CommandPaletteLabelandCommandPaletteCollection- a labeled section of a grouped list.CommandPaletteSeparator,CommandPaletteStatusandCommandPaletteFooter- a divider, a persistent status line (a loading message, a result count) and a row under the list for keyboard hints.
The query starts empty each time the palette opens. Choosing an item doesn't write it into the input, so a palette that stays open keeps the reader's query.
Examples
Default
Grouped commands with icons and a footer of keyboard hints. Press ⌘J (Ctrl+J on Windows and Linux) to open it from anywhere on the page. This site's own search already takes ⌘K, the usual choice for an app.
Navigation
Render items as links with render. Enter follows the highlighted link, and the palette closes as the page changes. With a router, render its link component instead: render={<Link href={page.url} />}.
Async results
For results from a server, control the query with value and onValueChange, set filter={null} so the palette shows items as they arrive, and put a Spinner in the input's endSlot while a request is in flight. onOpenChangeComplete clears the query once the palette has closed.
Keep it open
closeOnSelect={false} keeps the palette open after an item runs, for toggles and other commands people chain. Mark the state with aria-checked so screen readers hear it too.
Appearance
Every part takes the props of the component it's built from. frame={false} drops the glass frame for a plain card, backdrop={false} removes the dimmed layer (and with it the frame), the input's variant switches between soft and outline, and startSlot={null} removes its search icon. size on the root scales the input, items and labels together.
RTL
Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior follows the same direction.
The palette portals to <body>, so set dir="rtl" on CommandPaletteContent when only part of the page is right-to-left. For setup details and caveats, see the RTL guide.
API reference
CommandPalette combines Base UI's Dialog and Autocomplete. Each part forwards every remaining prop to the matching Base UI primitive - the tables below list the Appica additions and the most common props.
CommandPalette
The root. Holds the open state and the data; renders no DOM of its own.
CommandPaletteTrigger
A button that opens the palette.
Also forwards every native <button> prop (onClick, aria-*, ref, …).
CommandPaletteContent
The portalled dialog that holds the input, the list and the footer.
CommandPaletteInput
The search field. Renders Base UI's Input inside an InputGroup, styled like Input.
Also forwards every native <input> prop (onKeyDown, aria-*, ref, …).
CommandPaletteList
The scrollable list of commands.
CommandPaletteItem
One command in the list.
CommandPaletteEmpty
Shown only when the filter matches nothing - otherwise it renders nothing.
CommandPaletteStatus
A persistent line that stays mounted (e.g. a loading or count message), unlike CommandPaletteEmpty.
CommandPaletteGroup
Wraps one labeled section of a grouped list.
CommandPaletteLabel
The visible label for a CommandPaletteGroup.
CommandPaletteCollection
Renders the items inside a CommandPaletteGroup.
CommandPaletteSeparator
A thin divider between sections.
CommandPaletteFooter
A row under the list, usually keyboard hints built from Kbd.
Accessibility
CommandPaletteContentis a modal dialog named bylabel, which is rendered as a visually hidden title. Focus moves to the input when it opens and is trapped inside until it closes.- The input has
role="combobox"and controls alistboxofoptions througharia-activedescendant, so focus stays in the field while the highlight moves. - ↑/↓ move the highlight, Enter runs the highlighted item, Escape closes the palette, and typing filters the list.
shortcuttoggles it from anywhere on the page. - The first match is always highlighted, so Enter runs it without a separate keystroke.
- A toggle item that stays open should announce its state with
aria-checked, as in Keep it open. - Enter and exit transitions are skipped when the user prefers reduced motion.