# Command palette

A searchable command surface with grouped results and keyboard control.

## Web 0.2.0

### Usage

Supply named commands and execute the selected command in the parent. Make the empty search result actionable.

### Accessibility

Label the search and preserve active-result navigation, Enter activation and Escape dismissal. Keep focus restoration on close.

### When to use

Use for fast command discovery across an application. Keep essential actions available through ordinary navigation too.

### Install

Add this registry to your project's components.json once, before the first install. Keep your existing settings and other registries.

```json
{
  "registries": {
    "@maeso": "http://127.0.0.1:4321/r/{name}.json"
  }
}
```

Then install the registry's default theme once, and import its sheet in the CSS entry that imports Tailwind. It paints every item from this registry.

```sh
npx shadcn@latest add @maeso/maeso
```

```css
@import "./styles/theme.web.css";
```

```sh
npx shadcn@latest add @maeso/command-palette
```

### Props

#### CommandPalette

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| commands | readonly Command[] \| undefined | no |  |
| contained | boolean \| undefined | no |  |
| emptyLabel | string \| undefined | no |  |
| footer | ReactNode | no | Pass `null` to drop the hint bar entirely. |
| initialQuery | string \| undefined | no | What the field already holds when the palette opens: a query a capture reaches untyped. |
| onClose | (() => void) \| undefined | no |  |
| open | boolean \| undefined | no |  |
| openShortcut | string \| undefined | no | The chord that opens the palette, shown at the hint bar's end as "Search anywhere". |
| placeholder | string \| undefined | no |  |
| search | ((query: string) => readonly Command[]) \| undefined | no | The rows for one query, where the caller searches more than labels. Given, it replaces the<br>palette's own filter and `commands` is ignored. |
| style | CSSProperties \| undefined | no |  |

### Proof

#### Contrast

measured on 0.2.0

| State | Foreground | Background | Ratio | Floor |
| --- | --- | --- | --- | --- |
| default | rgb(7 21 34) | rgb(239 239 239) | 16.03 | AA 4.5 |
| default (dark) | rgb(248 245 240) | rgb(107 107 107) | 4.90 | AA 4.5 |

#### Keyboard

measured on 0.2.0

| Key | Action |
| --- | --- |
| Enter | Open the palette or run the active command and return focus |
| ArrowDown | Move the active command down |
| ArrowUp | Move the active command up |
| Tab | Keep forward focus in the palette |
| Shift+Tab | Keep backward focus in the palette |
| Escape | Dismiss without another command and restore focus |

#### Size

62268 gzip bytes · measured on 0.2.0

### Motion

The scrim fades and the command panel enters above it.

Configured duration: 200 ms

Reduced motion: none

#### Motion timing

Observed duration: 200 ms · measured on 0.2.0

#### Reduced motion

passed · measured on 0.2.0

### Example

```tsx
import { CommandPalette } from "@/components/ui/_kit/overlay/command-palette/CommandPalette";
import { useState } from "react";

export default function Example() {
const [open, setOpen] = useState(false);
return <><button onClick={() => setOpen(true)}>Open commands</button><CommandPalette open={open} onClose={() => setOpen(false)} commands={[{ id: "new", label: "New document", icon: "file-plus" }]} /></>;
}

```

### Preview · 0.2.0

not on native yet
