UnflowUI
Components

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 closeOnSelect is false)
  • 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

PropTypeDefaultDescription
groupsCommandPaletteGroup[]—Required. Results, already filtered by the app. Empty groups are skipped
openboolean—Controlled open state
defaultOpenbooleanfalseInitial open state when uncontrolled
onOpenChange(open: boolean) => void—Fired when the palette opens or closes
hotkeystring[] | null['Mod', 'k']Keys that toggle the palette. null turns the hotkey off
querystring—Controlled query, including any mode prefix
defaultQuerystring''Initial query when uncontrolled
onQueryChange(query: string) => void—Fired with the raw query on every change
scopesCommandPaletteChoice—Segmented control at the end of the field, e.g. "Everywhere / This project"
filtersCommandPaletteChoice—Result type chips with counts. Tab and Shift+Tab in the field move between them
prefixModesCommandPalettePrefixMode[]—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
loadingboolean—Shows a loading state in the list
emptyStateReactNode'No results for "…"'Shown when the query matches nothing
footerHintsReactNode—Text at the end of the footer, e.g. "Type > for commands, @ for people"
placeholderstring'Search or type a command'Field placeholder
labelstring'Command palette'Accessible name of the dialog
closeOnSelectbooleantrueCloses the palette after an item is selected
disablePortalboolean—Renders in place instead of in a portal

Default strings are translated.

CommandPaletteGroup

FieldTypeDescription
idstringRequired. Stable group id
labelstringRequired. Group heading
itemsCommandPaletteItem[]Required. The group's results

CommandPaletteItem

FieldTypeDescription
idstringRequired. Stable item id
titlestringRequired. Main line
onSelect() => voidRequired. Runs on Enter or click
subtitleReactNodeSecond line. Highlighted only when it is a string
titleHighlightsreadonly HighlightRange[]Match ranges to highlight in title (see Highlighting)
subtitleHighlightsreadonly HighlightRange[]Same as titleHighlights, for a string subtitle
iconReactNodeLeading icon
shortcutstring[]Keys shown as a keycap legend at the end of the row. The palette does not listen for them
disabledbooleanSkipped by the arrow keys and not selectable

CommandPaletteChoice

FieldTypeDescription
options{ value: string; label: string; count?: number }[]Required. The choices. count shows next to a filter chip
valuestringRequired. The selected value
onValueChange(value: string) => voidRequired. Fired with the new value

CommandPalettePrefixMode

FieldTypeDescription
prefixstringRequired. Typed at the start of the query to enter the mode, e.g. > or @
labelstringRequired. Shown as a tag in the field while the mode is active, e.g. "Commands"
placeholderstringPlaceholder 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

  • scopes renders a segmented control at the end of the field, for where to search.
  • filters renders result type chips under the field. Pass a count with each option to show how many results each type has. Tab and Shift+Tab in the field move between chips.
  • prefixModes turns a leading character into a mode. Typing > with the modes below shows a "Commands" tag in the field and swaps the placeholder. onModeChange reports the mode and the term after the prefix; onQueryChange still 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:

ExportSignatureDescription
highlightMatch(text, query, markClassName?) => ReactNodeWraps each match of query in a <mark>, ignoring case and diacritics
markRanges(text, ranges, markClassName?) => ReactNodeWraps 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 PropPropsDescription
headerBaseHTMLProps<HTMLDivElement>The field row (search field and scopes)
listBaseHTMLProps<HTMLDivElement>The scrolling results list
footerBaseHTMLProps<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).