CommandPalette
A keyboard-first command palette in a dialog, with grouped results, scopes, result type filters, prefix modes and match highlighting.
Overview
CommandPalette opens a search dialog on Mod+K (⌘K on Apple platforms, Ctrl+K elsewhere). Your app owns the search: it reads the query from onQueryChange and passes back groups that are already filtered. The palette handles the rest of the interaction:
- moves through every group with the arrow keys, skipping disabled items and wrapping around
- runs an item only on Enter or click, then closes (unless
closeOnSelectisfalse) - highlights matches in each title and string subtitle
- announces the result count, and says when nothing matches
- closes on Esc and gives focus back to the element that opened it
Long result lists stay fast: above 100 items, only the rows near the viewport are mounted.
Import
import { CommandPalette } from '@unflowio/ui/components/CommandPalette';Props
| Prop | Type | Default | Description |
|---|---|---|---|
groups | CommandPaletteGroup[] | — | Required. Results, already filtered by the app. Empty groups are skipped |
open | boolean | — | Controlled open state |
defaultOpen | boolean | false | Initial open state when uncontrolled |
onOpenChange | (open: boolean) => void | — | Fired when the palette opens or closes |
hotkey | string[] | null | ['Mod', 'k'] | Keys that toggle the palette. null turns the hotkey off |
query | string | — | Controlled query, including any mode prefix |
defaultQuery | string | '' | Initial query when uncontrolled |
onQueryChange | (query: string) => void | — | Fired with the raw query on every change |
scopes | CommandPaletteChoice | — | Segmented control at the end of the field, e.g. "Everywhere / This project" |
filters | CommandPaletteChoice | — | Result type chips with counts. Tab and Shift+Tab in the field move between them |
prefixModes | CommandPalettePrefixMode[] | — | Modes entered by typing a prefix at the start of the query, e.g. > or @ |
onModeChange | (mode: CommandPalettePrefixMode | null, term: string) => void | — | Fired when the query enters or leaves a prefix mode, with the query after the prefix |
loading | boolean | — | Shows a loading state in the list |
emptyState | ReactNode | 'No results for "…"' | Shown when the query matches nothing |
footerHints | ReactNode | — | Text at the end of the footer, e.g. "Type > for commands, @ for people" |
placeholder | string | 'Search or type a command' | Field placeholder |
label | string | 'Command palette' | Accessible name of the dialog |
closeOnSelect | boolean | true | Closes the palette after an item is selected |
disablePortal | boolean | — | Renders in place instead of in a portal |
Default strings are translated.
CommandPaletteGroup
| Field | Type | Description |
|---|---|---|
id | string | Required. Stable group id |
label | string | Required. Group heading |
items | CommandPaletteItem[] | Required. The group's results |
CommandPaletteItem
| Field | Type | Description |
|---|---|---|
id | string | Required. Stable item id |
title | string | Required. Main line |
onSelect | () => void | Required. Runs on Enter or click |
subtitle | ReactNode | Second line. Highlighted only when it is a string |
titleHighlights | readonly HighlightRange[] | Match ranges to highlight in title (see Highlighting) |
subtitleHighlights | readonly HighlightRange[] | Same as titleHighlights, for a string subtitle |
icon | ReactNode | Leading icon |
shortcut | string[] | Keys shown as a keycap legend at the end of the row. The palette does not listen for them |
disabled | boolean | Skipped by the arrow keys and not selectable |
CommandPaletteChoice
| Field | Type | Description |
|---|---|---|
options | { value: string; label: string; count?: number }[] | Required. The choices. count shows next to a filter chip |
value | string | Required. The selected value |
onValueChange | (value: string) => void | Required. Fired with the new value |
CommandPalettePrefixMode
| Field | Type | Description |
|---|---|---|
prefix | string | Required. Typed at the start of the query to enter the mode, e.g. > or @ |
label | string | Required. Shown as a tag in the field while the mode is active, e.g. "Commands" |
placeholder | string | Placeholder while the mode is active |
Basic usage
The preview turns the hotkey off with hotkey={null}, because this site uses ⌘K for its own search. Use the button to open it.
const [query, setQuery] = useState('');
const groups = useSearchResults(query);
<CommandPalette query={query} onQueryChange={setQuery} groups={groups} />With no open prop the palette manages its own open state and toggles on Mod+K. Pass open and onOpenChange to also open it from a button or a menu item.
Scopes, filters and prefix modes
scopesrenders a segmented control at the end of the field, for where to search.filtersrenders result type chips under the field. Pass acountwith each option to show how many results each type has. Tab and Shift+Tab in the field move between chips.prefixModesturns a leading character into a mode. Typing>with the modes below shows a "Commands" tag in the field and swaps the placeholder.onModeChangereports the mode and the term after the prefix;onQueryChangestill receives the raw query, prefix included.
<CommandPalette
query={query}
onQueryChange={setQuery}
groups={groups}
scopes={{
value: scope,
onValueChange: setScope,
options: [
{ value: 'everywhere', label: 'Everywhere' },
{ value: 'project', label: 'This project' },
],
}}
filters={{
value: filter,
onValueChange: setFilter,
options: [
{ value: 'all', label: 'All', count: 12 },
{ value: 'files', label: 'Files', count: 3 },
],
}}
prefixModes={[
{ prefix: '>', label: 'Commands', placeholder: 'Run a command' },
{ prefix: '@', label: 'People', placeholder: 'Find a person' },
]}
onModeChange={(mode, term) => setMode(mode?.prefix ?? null)}
footerHints="Type > for commands, @ for people"
/>Highlighting
By default the palette highlights the query itself in each title and string subtitle, ignoring case and diacritics ("cafe" matches "Café").
When the matches come from somewhere else, for example a search service that matches on stems, synonyms or a snippet, pass the exact ranges with titleHighlights and subtitleHighlights. Each range is a [start, end) pair of offsets into the string, in UTF-16 code units: the same indices String.prototype.slice uses. When an item has ranges, the palette uses them instead of matching the query; an empty array shows no highlight. Ranges are clamped to the string, empty or invalid ones are dropped, and overlapping ones are merged.
const title = '…the limitation of liability in the draft caps at 12 months of fees…';
const item: CommandPaletteItem = {
id: 'message-liability',
title,
titleHighlights: [
[5, 15],
[19, 28],
],
onSelect: () => openMessage('liability'),
};If your service returns offsets in bytes or code points, convert them to UTF-16 indices before passing them in. Otherwise, characters outside the Basic Multilingual Plane, such as emoji, shift the highlight.
The same helpers are exported for use elsewhere, e.g. to highlight matches in your own result rows:
| Export | Signature | Description |
|---|---|---|
highlightMatch | (text, query, markClassName?) => ReactNode | Wraps each match of query in a <mark>, ignoring case and diacritics |
markRanges | (text, ranges, markClassName?) => ReactNode | Wraps the given ranges of text in <mark> |
findMatches | (text, query) => [number, number][] | Ranges of text that match query, ignoring case and diacritics |
normalizeRanges | (ranges, length) => [number, number][] | Clamps, drops empty or invalid ranges, sorts and merges overlaps |
Text always renders as text, never as HTML.
Customization (slotProps)
| Slot Prop | Props | Description |
|---|---|---|
header | BaseHTMLProps<HTMLDivElement> | The field row (search field and scopes) |
list | BaseHTMLProps<HTMLDivElement> | The scrolling results list |
footer | BaseHTMLProps<HTMLDivElement> | The footer with keyboard hints |
Accessibility
- Renders a modal dialog named by
label. Focus moves into the field when it opens and returns to the element that opened it on close. - The field is a combobox that controls the results listbox. Each group is a labelled group of options, and the active option is tracked with
aria-activedescendant, so focus stays in the field while you arrow through results. - The result count is announced politely as it changes, including when nothing matches.
- Item shortcuts are a visual legend only. If an item has a global shortcut, register it separately (e.g. with
useHotkey).