CommandPalette
Search grouped commands and navigation targets from an inline surface.
Anatomy#
Group labels and items flatten into sibling rows when virtualized. With descriptionPosition: 'trailing', the description renders inside itemLabel.
Usage#
Use CommandPalette for searchable commands or navigation targets on an inline surface. The application decides when to open it and registers any global shortcut. Wrap it in a Dialog or BaseDialog when the palette should occupy a focused overlay; the wrapper also owns Escape dismissal. Use NavigationMenu for persistent site destinations.
Groups, filtering, and selection#
Pass items and groups from application state. The palette filters the supplied collection and calls
the item’s onSelect, then the palette’s onSelect. Fetching commands, routing, and global
shortcuts stay with the application. The default filterMethod is 'contains'; it matches the
item’s label, value, description, and keywords ignoring case and accents. Pass 'startsWith',
'endsWith', or a predicate for custom matching, or false to skip filtering when you already
filter the collection. Set alwaysShow on an item to keep it visible for any query.
By default, selecting an enabled item also calls onClose. The palette never hides itself: use
onClose to close the surrounding Dialog or BaseDialog. Set closable to show a close button that calls
onClose. The search input takes focus on mount unless the palette sits inside an element with
role="dialog"; set autofocus={false} to disable it. Control the query with searchValue and
onSearchValueChange, or start from defaultSearchValue.
Custom item layout and states#
Use itemRender when a row needs extra fields such as owner or status; it replaces the default row
content, so the items’ leadingRender and trailingRender no longer apply. Provide emptyRender
when an empty query or a miss needs explanation, and footerRender for a footer such as keyboard
hints. Set loading while results are still arriving: it swaps the leading icon for loadingIcon,
and items stay selectable.
Sub-navigation is a short, deliberate branch of commands. Swap the items prop from application
state rather than treating the palette as an application shell. Set closeOnSelect={false} while
the branch stays open.
Keyboard interaction#
| Key | Description |
|---|---|
| ↓ | Highlights the next enabled command. |
| ↑ | Highlights the previous enabled command. |
| ↵ | Selects the highlighted command. |
Focus stays in the search input while the highlight moves. Navigation wraps from the last command to the first. Escape and other dismissal keys belong to the enclosing Dialog or BaseDialog, not the palette.
Examples#
Jump to a workspace section#
Filter grouped destinations and store the selected section in page state.
Scan projects by owner and status#
Render each command row with extra fields. Keep matching against the item model.
Explain a failed search#
Replace the default empty copy when the query matches nothing.
Empty palette copy#
Show an empty collection with an explicit no-results message.
Wait for command results#
Keep the palette visible while loading is true.
Search ten thousand commands#
Pass a virtualizer from createListVirtualizer to render only the rows near the viewport. Its
entries are CommandPaletteT.VirtualEntry rows: group labels and commands flattened into one list.
The listbox keeps its default bounded height, so the virtual range stays stable while scrolling.
Drill into Create or Share#
Swap items to open a short command branch. Keep selection from closing the palette until the
user finishes or goes back.
API Reference#
Attributes#
data-disableddata-highlighteddata-loadingProps#
Renders a <div> element by default.