CommandPalette
import { CommandPalette } from '@tangible/ui';
Interactive docs and examples: CommandPalette in Storybook.
CommandPalette props
| Prop | Type | Default | Description |
|---|---|---|---|
children? |
ReactNode |
CommandPalette.Groups and CommandPalette.Items. |
|
className? |
string |
||
defaultOpen? |
boolean |
false |
Initial state when open is uncontrolled: enough for a palette opened only by its shortcut. A separate Trigger needs controlled open. |
filter? |
CommandPaletteFilter | false |
case-insensitive substring match on the item's text or any keyword |
Custom match for built-in filtering, or false to show every item. Ignored when inputValue is controlled. |
inputValue? |
string |
The search text (controlled). Controlling it hands filtering to you: every item you render is shown, so filter (or fetch) before rendering. Leave it uncontrolled and the palette filters items by their text and keywords. |
|
labels? |
Partial<CommandPaletteLabels> |
||
onInputChange? |
(value: string) => void |
Called with the search text on every change. | |
onOpenChange? |
(open: boolean) => void |
Called to open or close: Escape, the backdrop, a selection, the shortcut. | |
onRetry? |
() => void |
Shows a retry button in the error state. |
|
onSelect? |
(value: OptionValue, detail: CommandPaletteSelectDetail) => void |
Called when an item is chosen with Enter or a click. When it's omitted, an item with an href navigates there (http, https and relative URLs only). Opening an href in a new tab (Cmd/Ctrl+Enter, Cmd/Ctrl+click, middle-click) never calls it: items are options, not links, so these are the only new-tab routes. |
|
open? |
boolean |
Whether the palette is showing (controlled). Pair with onOpenChange. |
|
restoreFocusTo? |
RefObject<HTMLElement | null> | (() => HTMLElement | null) |
Where focus returns on close. Defaults to whatever had focus on open. | |
shortcut? |
string |
A global shortcut that toggles the palette, e.g. "mod+k" (mod is Cmd on Apple platforms, Ctrl elsewhere). Omit for none. A shortcut without mod or alt (such as "/") is ignored while the user is typing in a field. Avoid alt+<letter> on macOS, where Option changes the character. The shortcut stands down while another modal dialog is open. |
|
showHints? |
boolean |
true |
Show the keyboard hints footer. It is hidden on narrow screens regardless. |
status? |
"error" | "loading" | "ready" |
'ready' |
loading and error show a message under the results, which is also announced. Items you still render stay visible and navigable. |
Also accepts the standard attributes of HTMLAttributes (data-*, aria-*, event handlers), passed to the element it renders.
CommandPalette.Item
Also exported as CommandPaletteItem.
| Prop | Type | Default | Description |
|---|---|---|---|
value |
OptionValue |
Handed to onSelect. Unique within the palette. |
|
children? |
ReactNode |
||
className? |
string |
||
description? |
ReactNode |
A second, muted line. | |
disabled? |
boolean |
false |
|
href? |
string |
A destination. Cmd/Ctrl+Enter opens it in a new tab. | |
icon? |
IconSource |
A leading icon. | |
keepOpen? |
boolean |
false |
Keep the palette open after this item is chosen. |
keywords? |
string[] |
[] |
Extra words that match in built-in filtering but aren't shown. |
textValue? |
string |
Searchable text, when children isn't a plain string. |
CommandPalette.Group
Also exported as CommandPaletteGroup.
| Prop | Type | Default | Description |
|---|---|---|---|
children? |
ReactNode |
||
className? |
string |
CommandPalette.Label
Also exported as CommandPaletteLabel.
| Prop | Type | Default | Description |
|---|---|---|---|
children? |
ReactNode |
||
className? |
string |
CommandPalette.Trigger
Also exported as CommandPaletteTrigger.
| Prop | Type | Default | Description |
|---|---|---|---|
children? |
ReactNode |
defaultCommandPaletteLabels.placeholder ("Search…") |
Visible text, which is also the button's accessible name. |
shortcut? |
string |
Shown as a key hint and in aria-keyshortcuts, e.g. "mod+k". Display only: it registers nothing, so match the palette's own shortcut. |
|
size? |
"lg" | "md" | "sm" |
'md' |
Control height tier, as for the form controls. App headers usually want sm. |
Also accepts the standard attributes of ButtonHTMLAttributes (data-*, aria-*, event handlers), passed to the element it renders.
Other exports
defaultCommandPaletteLabels:CommandPaletteLabels
Examples
-
Keyboard Flow: Keyboard flow: the shortcut opens it, type, arrow, Enter, focus returns.
-
Item States: A disabled item (skipped by the arrows, ignores clicks), a
keepOpenitem and description lines. A disabled trigger is a plain disabled button. -
Links: No
onSelect: an item with anhrefnavigates (http, https and relative URLs only). Cmd/Ctrl+Enter opens it in a new tab and the palette stays open; the field's description tells AT about that key. -
Loading: The
loadingstate: the message shows and is announced; the list is busy. -
Error: The
errorstate withonRetry. Retry hands focus back to the field. -
No Results: Nothing matched, with built-in filtering.
-
Async Results: Controlled
inputValue: the consumer fetches, the palette showsstatus. -
Sizes: The header trigger at each size, and disabled. Headers usually want
sm.
Other stories: Basic (interactive page).
Component API tokens
Read via fallback, never declared. Set one on an ancestor to restyle every instance under it.
--tui-command-palette-width--tui-command-palette-offset-top--tui-command-palette-list-max-height--tui-command-palette-option-bg-hover--tui-command-palette-option-fg-hover--tui-command-palette-option-indicator--tui-command-palette-kbd-bg--tui-command-palette-kbd-fg--tui-command-palette-trigger-bg--tui-command-palette-trigger-fg--tui-command-palette-trigger-border--tui-command-palette-trigger-border-hover--tui-command-palette-trigger-radius