Tangible Design System · @tangible/ui 0.2.46 · Interactive version · Markdown

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

Examples

Other stories: Basic (interactive page).

Component API tokens

Read via fallback, never declared. Set one on an ancestor to restyle every instance under it.