---
title: "Command Palette"
description: "A searchable quick switcher of grouped destinations and actions, driven from the keyboard."
---

A search field over a list of destinations and actions. Its dialog shell is built on [Radix Dialog](https://www.radix-ui.com/primitives/docs/components/dialog) in React and [Reka UI Dialog](https://reka-ui.com/docs/components/dialog) in Vue. The search field and the list are newt/ui's own.

Use it to give keyboard users one place to jump anywhere or run anything: switch channel, open settings, mention a member. It complements the visible navigation and never replaces it, because nothing on screen says the palette exists. Bind it to a shortcut and offer a button too.

Typing narrows the list to the rows whose label, description or `keywords` contain the query. The palette filters the rows it is given; for results from a server, pass new `groups` as the query changes.

_Live example of Command Palette — see the page for the rendered demo._

## Installation

```bash
npx newtui@latest add command-palette
```

npm dependencies: React: radix-ui. Vue: reka-ui.

Files written — React: components/ui/command-palette.tsx. Vue: components/ui/command-palette/CommandPalette.vue, components/ui/command-palette/index.ts.

## Usage

React:

```tsx
import { CommandPalette } from "@/components/ui/command-palette"
```

Vue:

```ts
import { CommandPalette } from "@/components/ui/command-palette"
```

## API reference

**`CommandPalette`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open / v-model:open` | `boolean` | `false` | Whether the palette is shown. |
| `onOpenChange` | `(open: boolean) => void` | — | React only. Called with `false` on Escape, a press of the overlay or a selection; Vue emits `update:open`. |
| `groups` | `{ label: string; items: CommandItem[] }[]` | — | The rows, under their headings. A group with no matching row is hidden. |
| `onSelect / @select` | `(item: CommandItem) => void` | — | Called with the chosen row. The palette then closes itself. |
| `label` | `string` | `"Command palette"` | Accessible name of the dialog and of the list. |
| `placeholder` | `string` | `"Where would you like to go?"` | Placeholder and accessible name of the search field. |
| `emptyText` | `string` | `"Nothing matches that."` | Shown when the query matches nothing. |
| `hints` | `{ move: string; select: string; close: string } \| false` | — | The wording of the footer's key hints. `false` leaves the footer out. |
| `container` | `HTMLElement` | `document.body` | Element the overlay and panel are portalled into. A palette below a `DirectionProvider` or a themed wrapper passes that element to keep the direction and the palette. |

**`CommandItem`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | — | Unique across the whole palette. |
| `label` | `string` | — | The row's main text. |
| `description` | `string` | — | Quieter text beside the label. |
| `prefix` | `string` | — | A one-character sign before the label, such as `#` or `@`. |
| `shortcut` | `string` | — | A key combination shown at the end of the row. |
| `keywords` | `string[]` | — | Extra words the search matches that the row does not show. |

Opening the palette always starts from an empty query with the first row highlighted.

## Accessibility

The shell carries `role="dialog"` and `aria-modal="true"`, and takes its accessible name from `label`. The primitive holds focus inside it and hides the page behind from screen readers. `Escape` closes it, and so does a press on the dimmed page. While an input method composes text, `Escape` cancels the candidate and the palette stays open. When the palette closes, focus goes back to the element that had it before. The search field is a `role="combobox"` that keeps focus the whole time: `Up` and `Down` move the highlight, wrapping at the ends, and `aria-activedescendant` tells a screen reader which row is highlighted. `Enter` chooses it. Rows are `role="option"` inside a `role="listbox"`, grouped under their headings. The footer hints repeat what the keys do for sighted users and are hidden from assistive technology.

`label`, `placeholder`, `emptyText` and `hints` default to English. [Translating labels](/docs/translating-labels) lists every English default.

## Tokens

Command Palette reads its colours, radii and motion from the `--newt-*` tokens. Override a token rather than editing the component.
