# CommandPalette

```tsx
import { CommandPalette } from '@tangible/ui';
```

Interactive docs and examples: [CommandPalette in Storybook](https://design.tangible.one/?path=/docs/overlays-commandpalette--docs).

## CommandPalette props

| Prop | Type | Default | Description |
| - | - | - | - |
| `children?` | `ReactNode` | | `CommandPalette.Group`s and `CommandPalette.Item`s. |
| `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](https://design.tangible.one/?path=/story/overlays-commandpalette--keyboard-flow): Keyboard flow: the shortcut opens it, type, arrow, Enter, focus returns.

- [Item States](https://design.tangible.one/?path=/story/overlays-commandpalette--item-states): A disabled item (skipped by the arrows, ignores clicks), a `keepOpen` item
  and description lines. A disabled trigger is a plain disabled button.

- [Links](https://design.tangible.one/?path=/story/overlays-commandpalette--links): No `onSelect`: an item with an `href` navigates (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](https://design.tangible.one/?path=/story/overlays-commandpalette--loading): The `loading` state: the message shows and is announced; the list is busy.

- [Error](https://design.tangible.one/?path=/story/overlays-commandpalette--error-state): The `error` state with `onRetry`. Retry hands focus back to the field.

- [No Results](https://design.tangible.one/?path=/story/overlays-commandpalette--no-results): Nothing matched, with built-in filtering.

- [Async Results](https://design.tangible.one/?path=/story/overlays-commandpalette--async-results): Controlled `inputValue`: the consumer fetches, the palette shows `status`.

- [Sizes](https://design.tangible.one/?path=/story/overlays-commandpalette--sizes): The header trigger at each size, and disabled. Headers usually want `sm`.

Other stories: Basic ([interactive page](https://design.tangible.one/?path=/docs/overlays-commandpalette--docs)).

## 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`

---

Interactive version: https://design.tangible.one/?path=/docs/overlays-commandpalette--docs
