# Command Palette (/ui/components/react/command-palette)


## Usage [#usage]

```tsx
import {
  CommandPalette,
  CommandPaletteTrigger,
  CommandPaletteContent,
  CommandPaletteInput,
  CommandPaletteList,
  CommandPaletteItem,
  CommandPaletteEmpty,
} from '@appica/ui-react/command-palette'
import { Button } from '@appica/ui-react/button'
```

```tsx
<CommandPalette items={commands} shortcut="k">
  <CommandPaletteTrigger render={<Button variant="outline">Search</Button>} />
  <CommandPaletteContent>
    <CommandPaletteInput placeholder="Type a command or search…" />
    <CommandPaletteList>
      {(command) => (
        <CommandPaletteItem key={command.value} value={command} onClick={command.run}>
          {command.label}
        </CommandPaletteItem>
      )}
    </CommandPaletteList>
    <CommandPaletteEmpty>No commands found.</CommandPaletteEmpty>
  </CommandPaletteContent>
</CommandPalette>
```

`CommandPalette` is a [Dialog](/ui/components/react/dialog) with an [Autocomplete](/ui/components/react/autocomplete) inside it, built on Base UI's [Dialog](https://base-ui.com/react/components/dialog) and [Autocomplete](https://base-ui.com/react/components/autocomplete). Typing filters the list, the first match is always highlighted, and Enter runs it:

- **`CommandPalette`** - the root. Holds the open state and the data: pass `items` (flat, or grouped as `{ value, items }`) and, for object items, a `label` or an `itemToStringValue` the filter can read. `shortcut` adds a ⌘ or Ctrl key combination that opens and closes it.
- **`CommandPaletteTrigger`** - an optional button that opens the palette. Project it onto your own [`Button`](/ui/components/react/button) with `render`.
- **`CommandPaletteContent`** - the portalled dialog, near the top of the screen. It takes the [Dialog](/ui/components/react/dialog)'s `backdrop` and `frame`, and the same `backdropProps`, `viewportProps` and `portalProps` escape hatches.
- **`CommandPaletteInput`** - the search field, styled like [`Input`](/ui/components/react/input). It takes focus when the palette opens.
- **`CommandPaletteList`** - the scrollable list. Pass a render function over the filtered items.
- **`CommandPaletteItem`** - one command. Run it from `onClick`, which also fires on Enter, or make it a link with `render={<a href="…" />}`. It closes the palette unless `closeOnSelect={false}`.
- **`CommandPaletteEmpty`** - shown only when nothing matches.
- **`CommandPaletteGroup`**, **`CommandPaletteLabel`** and **`CommandPaletteCollection`** - a labeled section of a grouped list.
- **`CommandPaletteSeparator`**, **`CommandPaletteStatus`** and **`CommandPaletteFooter`** - a divider, a persistent status line (a loading message, a result count) and a row under the list for keyboard hints.

The query starts empty each time the palette opens. Choosing an item doesn't write it into the input, so a palette that stays open keeps the reader's query.

## Examples [#examples]

### Default [#default]

Grouped commands with icons and a footer of keyboard hints. Press ⌘J (Ctrl+J on Windows and Linux) to open it from anywhere on the page. This site's own search already takes ⌘K, the usual choice for an app.

```tsx
'use client'

import { Button } from '@appica/ui-react/button'
import {
  CommandPalette,
  CommandPaletteTrigger,
  CommandPaletteContent,
  CommandPaletteInput,
  CommandPaletteList,
  CommandPaletteGroup,
  CommandPaletteLabel,
  CommandPaletteCollection,
  CommandPaletteItem,
  CommandPaletteEmpty,
  CommandPaletteFooter,
} from '@appica/ui-react/command-palette'
import { Kbd, KbdGroup } from '@appica/ui-react/kbd'
import { Bell, CreditCard, LayoutDashboard, Moon, Plus, Search, Settings, UserPlus } from '@appica/icons-react'

const GROUPS = [
  {
    value: 'Pages',
    items: [
      { value: 'dashboard', label: 'Dashboard', icon: LayoutDashboard },
      { value: 'billing', label: 'Billing', icon: CreditCard },
      { value: 'notifications', label: 'Notifications', icon: Bell },
      { value: 'settings', label: 'Settings', icon: Settings },
    ],
  },
  {
    value: 'Actions',
    items: [
      { value: 'new-project', label: 'New project', icon: Plus },
      { value: 'invite', label: 'Invite a teammate', icon: UserPlus },
      { value: 'dark-mode', label: 'Switch to dark mode', icon: Moon },
    ],
  },
]

type Command = (typeof GROUPS)[number]['items'][number]

export default function CommandPaletteDefault() {
  return (
    <CommandPalette items={GROUPS} shortcut="j">
      <CommandPaletteTrigger
        className="text-foreground w-56 justify-start"
        render={
          <Button variant="soft">
            <Search data-icon="start" />
            <span className="text-foreground-subtle font-normal">Search…</span>
            <KbdGroup data-icon="end" className="ms-auto -me-1">
              <Kbd>⌘</Kbd>
              <Kbd>J</Kbd>
            </KbdGroup>
          </Button>
        }
      />
      <CommandPaletteContent>
        <CommandPaletteInput placeholder="Type a command or search…" />
        <CommandPaletteList>
          {(group: (typeof GROUPS)[number]) => (
            <CommandPaletteGroup key={group.value} items={group.items}>
              <CommandPaletteLabel>{group.value}</CommandPaletteLabel>
              <CommandPaletteCollection>
                {(command: Command) => (
                  <CommandPaletteItem key={command.value} value={command}>
                    <command.icon />
                    {command.label}
                  </CommandPaletteItem>
                )}
              </CommandPaletteCollection>
            </CommandPaletteGroup>
          )}
        </CommandPaletteList>
        <CommandPaletteEmpty>No commands found.</CommandPaletteEmpty>
        <CommandPaletteFooter>
          <span className="flex items-center gap-1.5">
            <KbdGroup>
              <Kbd>↑</Kbd>
              <Kbd>↓</Kbd>
            </KbdGroup>
            Navigate
          </span>
          <span className="flex items-center gap-1.5">
            <Kbd>↵</Kbd>
            Run
          </span>
          <span className="flex items-center gap-1.5">
            <Kbd>Esc</Kbd>
            Close
          </span>
        </CommandPaletteFooter>
      </CommandPaletteContent>
    </CommandPalette>
  )
}
```

### Navigation [#navigation]

Render items as links with `render`. Enter follows the highlighted link, and the palette closes as the page changes. With a router, render its link component instead: `render={<Link href={page.url} />}`.

```tsx
'use client'

import { Button } from '@appica/ui-react/button'
import {
  CommandPalette,
  CommandPaletteTrigger,
  CommandPaletteContent,
  CommandPaletteInput,
  CommandPaletteList,
  CommandPaletteItem,
  CommandPaletteEmpty,
} from '@appica/ui-react/command-palette'
import { FileText } from '@appica/icons-react'

const PAGES = [
  { value: 'button', label: 'Button', url: '/ui/components/react/button' },
  { value: 'dialog', label: 'Dialog', url: '/ui/components/react/dialog' },
  { value: 'drawer', label: 'Drawer', url: '/ui/components/react/drawer' },
  { value: 'input', label: 'Input', url: '/ui/components/react/input' },
  { value: 'select', label: 'Select', url: '/ui/components/react/select' },
  { value: 'tabs', label: 'Tabs', url: '/ui/components/react/tabs' },
  { value: 'tooltip', label: 'Tooltip', url: '/ui/components/react/tooltip' },
]

export default function CommandPaletteLinks() {
  return (
    <CommandPalette items={PAGES}>
      <CommandPaletteTrigger render={<Button variant="outline">Jump to a component</Button>} />
      <CommandPaletteContent label="Jump to a component">
        <CommandPaletteInput placeholder="Search components…" />
        <CommandPaletteList>
          {(page: (typeof PAGES)[number]) => (
            <CommandPaletteItem key={page.value} value={page} render={<a href={page.url} />}>
              <FileText />
              {page.label}
            </CommandPaletteItem>
          )}
        </CommandPaletteList>
        <CommandPaletteEmpty>No components found.</CommandPaletteEmpty>
      </CommandPaletteContent>
    </CommandPalette>
  )
}
```

### Async results [#async-results]

For results from a server, control the query with `value` and `onValueChange`, set `filter={null}` so the palette shows `items` as they arrive, and put a [Spinner](/ui/components/react/spinner) in the input's `endSlot` while a request is in flight. `onOpenChangeComplete` clears the query once the palette has closed.

```tsx
'use client'

import * as React from 'react'
import { Button } from '@appica/ui-react/button'
import {
  CommandPalette,
  CommandPaletteTrigger,
  CommandPaletteContent,
  CommandPaletteInput,
  CommandPaletteList,
  CommandPaletteItem,
  CommandPaletteEmpty,
} from '@appica/ui-react/command-palette'
import { Spinner } from '@appica/ui-react/spinner'
import { User } from '@appica/icons-react'

interface Person {
  value: string
  label: string
  email: string
}

const PEOPLE: Person[] = [
  { value: 'ada', label: 'Ada Lovelace', email: 'ada@example.com' },
  { value: 'alan', label: 'Alan Turing', email: 'alan@example.com' },
  { value: 'grace', label: 'Grace Hopper', email: 'grace@example.com' },
  { value: 'katherine', label: 'Katherine Johnson', email: 'katherine@example.com' },
  { value: 'linus', label: 'Linus Torvalds', email: 'linus@example.com' },
  { value: 'margaret', label: 'Margaret Hamilton', email: 'margaret@example.com' },
]

function searchPeople(query: string) {
  return new Promise<Person[]>((resolve) => {
    setTimeout(() => {
      const q = query.trim().toLowerCase()
      resolve(PEOPLE.filter((person) => person.label.toLowerCase().includes(q)))
    }, 400)
  })
}

export default function CommandPaletteAsync() {
  const [query, setQuery] = React.useState('')
  const [results, setResults] = React.useState(PEOPLE)
  const [loading, setLoading] = React.useState(false)

  React.useEffect(() => {
    let current = true
    setLoading(true)
    searchPeople(query).then((people) => {
      if (!current) return
      setResults(people)
      setLoading(false)
    })
    return () => {
      current = false
    }
  }, [query])

  return (
    <CommandPalette
      items={results}
      filter={null}
      value={query}
      onValueChange={setQuery}
      onOpenChangeComplete={(open) => !open && setQuery('')}
    >
      <CommandPaletteTrigger render={<Button variant="outline">Find a teammate</Button>} />
      <CommandPaletteContent label="Find a teammate">
        <CommandPaletteInput
          placeholder="Search people…"
          endSlot={loading ? <Spinner variant="dots" currentColor className="text-xl" /> : null}
        />
        <CommandPaletteList>
          {(person: Person) => (
            <CommandPaletteItem key={person.value} value={person}>
              <User />
              <span className="min-w-0 flex-1 truncate">{person.label}</span>
              <span className="text-foreground-subtle text-xs">{person.email}</span>
            </CommandPaletteItem>
          )}
        </CommandPaletteList>
        <CommandPaletteEmpty>{loading ? 'Searching…' : 'Nobody matches that name.'}</CommandPaletteEmpty>
      </CommandPaletteContent>
    </CommandPalette>
  )
}
```

### Keep it open [#keep-it-open]

`closeOnSelect={false}` keeps the palette open after an item runs, for toggles and other commands people chain. Mark the state with `aria-checked` so screen readers hear it too.

```tsx
'use client'

import * as React from 'react'
import { Button } from '@appica/ui-react/button'
import {
  CommandPalette,
  CommandPaletteTrigger,
  CommandPaletteContent,
  CommandPaletteInput,
  CommandPaletteList,
  CommandPaletteItem,
} from '@appica/ui-react/command-palette'
import { Check } from '@appica/icons-react'

const SETTINGS = [
  { value: 'line-numbers', label: 'Show line numbers' },
  { value: 'word-wrap', label: 'Wrap long lines' },
  { value: 'minimap', label: 'Show the minimap' },
  { value: 'whitespace', label: 'Render whitespace' },
]

export default function CommandPaletteKeepOpen() {
  const [enabled, setEnabled] = React.useState<string[]>(['line-numbers'])

  function toggle(value: string) {
    setEnabled((prev) => (prev.includes(value) ? prev.filter((v) => v !== value) : [...prev, value]))
  }

  return (
    <CommandPalette items={SETTINGS}>
      <CommandPaletteTrigger render={<Button variant="outline">Editor settings</Button>} />
      <CommandPaletteContent label="Editor settings">
        <CommandPaletteInput placeholder="Toggle a setting…" />
        <CommandPaletteList>
          {(setting: (typeof SETTINGS)[number]) => (
            <CommandPaletteItem
              key={setting.value}
              value={setting}
              aria-checked={enabled.includes(setting.value)}
              closeOnSelect={false}
              onClick={() => toggle(setting.value)}
            >
              <span className="min-w-0 flex-1">{setting.label}</span>
              <Check className={enabled.includes(setting.value) ? 'text-foreground-intense' : 'invisible'} />
            </CommandPaletteItem>
          )}
        </CommandPaletteList>
      </CommandPaletteContent>
    </CommandPalette>
  )
}
```

### Appearance [#appearance]

Every part takes the props of the component it's built from. `frame={false}` drops the glass frame for a plain card, `backdrop={false}` removes the dimmed layer (and with it the frame), the input's `variant` switches between `soft` and `outline`, and `startSlot={null}` removes its search icon. `size` on the root scales the input, items and labels together.

```tsx
'use client'

import { Button } from '@appica/ui-react/button'
import {
  CommandPalette,
  CommandPaletteTrigger,
  CommandPaletteContent,
  CommandPaletteInput,
  CommandPaletteList,
  CommandPaletteItem,
  CommandPaletteEmpty,
} from '@appica/ui-react/command-palette'

const LANGUAGES = [
  { value: 'en', label: 'English' },
  { value: 'de', label: 'Deutsch' },
  { value: 'es', label: 'Español' },
  { value: 'fr', label: 'Français' },
  { value: 'it', label: 'Italiano' },
  { value: 'ja', label: '日本語' },
]

export default function CommandPaletteAppearance() {
  return (
    <CommandPalette items={LANGUAGES} size="sm">
      <CommandPaletteTrigger render={<Button variant="outline">Change language</Button>} />
      <CommandPaletteContent label="Change language" frame={false} className="w-100">
        <CommandPaletteInput variant="outline" startSlot={null} placeholder="Language…" />
        <CommandPaletteList>
          {(language: (typeof LANGUAGES)[number]) => (
            <CommandPaletteItem key={language.value} value={language}>
              {language.label}
            </CommandPaletteItem>
          )}
        </CommandPaletteList>
        <CommandPaletteEmpty>No languages found.</CommandPaletteEmpty>
      </CommandPaletteContent>
    </CommandPalette>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The palette portals to `<body>`, so set `dir="rtl"` on `CommandPaletteContent` when only part of the page is right-to-left. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).


## API reference [#api-reference]

`CommandPalette` combines [Base UI's Dialog](https://base-ui.com/react/components/dialog) and [Autocomplete](https://base-ui.com/react/components/autocomplete). Each part forwards every remaining prop to the matching Base UI primitive - the tables below list the Appica additions and the most common props.

### CommandPalette [#commandpalette]

The root. Holds the open state and the data; renders no DOM of its own.

| Prop                      | Type              | Default | Description                                                                                                          |
| ------------------------- | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `items`                   | `readonly T[] \| { value, items }[]` | -       | The commands to filter. A flat array, or `{ value, items }` objects for groups.                                                                             |
| `shortcut`                | `string`                                                 | -       | Key that opens and closes the palette together with ⌘ or Ctrl, e.g. `'k'` for ⌘K.                                                                           |
| `size`                    | `'sm' \| 'md' \| 'lg'`                   | `'md'`  | Input height, item and label sizing.                                                                                                                        |
| `open`                    | `boolean`                                                | -       | Controlled open state. Pair with `onOpenChange`.                                                                                                            |
| `defaultOpen`             | `boolean`                                                | `false` | Uncontrolled initial open state.                                                                                                                            |
| `onOpenChange`            | `(open, details) => void`                | -       | Fires when the palette opens or closes.                                                                                                                     |
| `disablePointerDismissal` | `boolean`                                                | `false` | Keep the palette open when the backdrop is clicked.                                                                                                         |
| `value`                   | `string`                                                 | -       | Controlled query. Pair with `onValueChange`.                                                                                                                |
| `defaultValue`            | `string`                                                 | -       | Uncontrolled initial query.                                                                                                                                 |
| `onValueChange`           | `(value, details) => void`               | -       | Fires as the query changes.                                                                                                                                 |
| `filter`                  | `function \| null`                       | -       | Match items against the query. Return `true` to keep an item, or pass `null` to show all.                                                                   |
| `filteredItems`           | `array`                                                  | -       | Pre-filtered items to render, bypassing the built-in filter.                                                                                                |
| `itemToStringValue`       | `(item: T) => string`                    | -       | How the filter reads an object item without a `label`.                                                                                                      |
| `limit`                   | `number`                                                 | `-1`    | Maximum items to render. `-1` for no limit.                                                                                                                 |
| `modal`                   | `boolean`                                                | `true`  | Trap interaction inside the popup while it is open.                                                                                                         |
| `onOpenChangeComplete`    | `function`                                               | -       | Fires once the open/close animation finishes.                                                                                                               |
| `actionsRef`              | `Ref`                                                    | -       | Ref exposing imperative `close()` and `unmount()`. To unmount after your own exit animation, call `eventDetails.preventUnmountOnClose()` in `onOpenChange`. |
| `handle`                  | `Handle`                                                 | -       | Handle that lets detached triggers control this popup's open state.                                                                                         |
| `triggerId`               | `string`                                                 | -       | ID of the associated trigger. Use alongside `open` for a controlled popup.                                                                                  |
| `defaultTriggerId`        | `string`                                                 | -       | ID of the associated trigger. Use alongside `defaultOpen` for an initially open popup.                                                                      |
| `onItemHighlighted`       | `function`                                               | -       | Fires when an item is highlighted or unhighlighted.                                                                                                         |
| `locale`                  | `string`                                                 | -       | Locale used for string comparison. Defaults to the runtime locale.                                                                                          |
| `children`                | `ReactNode`                                              | -       | The trigger and the content.                                                                                                                                |

### CommandPaletteTrigger [#commandpalettetrigger]

A button that opens the palette.

| Prop           | Type                        | Default | Description                                                                  |
| -------------- | ------------------------------------------------------------------ | ------- | ---------------------------------------------------------------------------- |
| `nativeButton` | `boolean`                                                          | `true`  | Whether `render` produces a native `<button>`. Set `false` when it does not. |
| `handle`       | `Handle`                                                           | -       | Handle linking this trigger to a detached popup.                             |
| `payload`      | `unknown`                                                          | -       | Value passed to the popup when opened from this trigger.                     |
| `render`       | `ReactElement \| ((props, state) => ReactElement)` | -       | Compose the trigger with another element.                                    |
| `className`    | `string`                                                           | -       | Extra classes, merged via `tailwind-merge`.                                  |

Also forwards every native `<button>` prop (`onClick`, `aria-*`, `ref`, …).

### CommandPaletteContent [#commandpalettecontent]

The portalled dialog that holds the input, the list and the footer.

| Prop            | Type                        | Default             | Description                                                                                                            |
| --------------- | ------------------------------------------------------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `label`         | `string`                                                           | `'Command palette'` | Accessible name of the dialog, read by screen readers and kept out of sight.                                           |
| `backdrop`      | `boolean`                                                          | `true`              | Render the dimmed, blurred backdrop behind the palette.                                                                |
| `frame`         | `boolean`                                                          | `true`              | Wrap the palette in a translucent glass frame. Needs `backdrop`: without one the palette is always a plain solid card. |
| `backdropProps` | `object`                                                           | -                   | Escape hatch for the backdrop element (`className`, `style`, `render`).                                                |
| `viewportProps` | `object`                                                           | -                   | Escape hatch for the fixed layer that places the palette.                                                              |
| `portalProps`   | `object`                                                           | -                   | Escape hatch for the portal element.                                                                                   |
| `container`     | `HTMLElement \| ref \| null`                       | -                   | Portal target - render the palette into a different node.                                                              |
| `keepMounted`   | `boolean`                                                          | `false`             | Keep the palette mounted in the DOM while closed.                                                                      |
| `initialFocus`  | `boolean \| ref \| function`                       | -                   | Where focus goes when the palette opens. The input by default.                                                         |
| `finalFocus`    | `boolean \| ref \| function`                       | -                   | Where focus goes when the palette closes.                                                                              |
| `render`        | `ReactElement \| ((props, state) => ReactElement)` | -                   | Replace the underlying element, or compose it with another component.                                                  |
| `className`     | `string`                                                           | -                   | Extra classes on the palette, e.g. a width.                                                                            |

### CommandPaletteInput [#commandpaletteinput]

The search field. Renders Base UI's `Input` inside an `InputGroup`, styled like [`Input`](/ui/components/react/input).

| Prop          | Type                                                               | Default  | Description                                                                                                    |
| ------------- | ------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------- |
| `variant`     | `'outline' \| 'soft'`                              | `'soft'` | Input appearance, bordered or filled.                                                                          |
| `startSlot`   | `ReactNode`                                                        | -        | Adornment rendered before the field, inside the input frame. A search icon unless you pass your own or `null`. |
| `endSlot`     | `ReactNode`                                                        | -        | Adornment rendered after the field, inside the input frame.                                                    |
| `placeholder` | `string`                                                           | `' '`    | Placeholder text.                                                                                              |
| `disabled`    | `boolean`                                                          | `false`  | Disable user interaction.                                                                                      |
| `render`      | `ReactElement \| ((props, state) => ReactElement)` | -        | Replace the underlying element, or compose it with another component.                                          |
| `className`   | `string`                                                           | -        | Extra classes on the input group, merged via `tailwind-merge`.                                                 |

Also forwards every native `<input>` prop (`onKeyDown`, `aria-*`, `ref`, …).

### CommandPaletteList [#commandpalettelist]

The scrollable list of commands.

| Prop              | Type                        | Default | Description                                                                           |
| ----------------- | ------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------- |
| `children`        | `ReactNode \| (item, index) => ReactNode`          | -       | A render function over the filtered items, or static items.                           |
| `scrollAreaProps` | `object`                                                           | -       | Props forwarded to the scroll area around the list, e.g. a fixed `className="h-110"`. |
| `render`          | `ReactElement \| ((props, state) => ReactElement)` | -       | Replace the underlying element, or compose it with another component.                 |
| `className`       | `string`                                                           | -       | Extra classes, merged via `tailwind-merge`.                                           |

### CommandPaletteItem [#commandpaletteitem]

One command in the list.

| Prop            | Type                                                               | Default | Description                                                               |
| --------------- | ------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------- |
| `value`         | `T`                                                                | -       | The item this command represents.                                         |
| `closeOnSelect` | `boolean`                                                          | `true`  | Close the palette once the item runs, by click or Enter.                  |
| `onClick`       | `function`                                                         | -       | Runs the command. Enter on the highlighted item fires it too.             |
| `disabled`      | `boolean`                                                          | `false` | Disable user interaction.                                                 |
| `index`         | `number`                                                           | -       | The item's index in the list. Set it to skip automatic index calculation. |
| `nativeButton`  | `boolean`                                                          | `false` | Whether `render` produces a native `<button>`. Set `true` when it does.   |
| `children`      | `ReactNode`                                                        | -       | The content.                                                              |
| `render`        | `ReactElement \| ((props, state) => ReactElement)` | -       | Replace the underlying element, e.g. with a link.                         |
| `className`     | `string`                                                           | -       | Extra classes, merged via `tailwind-merge`.                               |

### CommandPaletteEmpty [#commandpaletteempty]

Shown only when the filter matches nothing - otherwise it renders nothing.

| Prop        | Type                                                               | Default | Description                                                           |
| ----------- | ------------------------------------------------------------------ | ------- | --------------------------------------------------------------------- |
| `render`    | `ReactElement \| ((props, state) => ReactElement)` | -       | Replace the underlying element, or compose it with another component. |
| `children`  | `ReactNode`                                                        | -       | The empty-state message.                                              |
| `className` | `string`                                                           | -       | Extra classes, merged via `tailwind-merge`.                           |

### CommandPaletteStatus [#commandpalettestatus]

A persistent line that stays mounted (e.g. a loading or count message), unlike `CommandPaletteEmpty`.

| Prop        | Type                                                               | Default | Description                                                           |
| ----------- | ------------------------------------------------------------------ | ------- | --------------------------------------------------------------------- |
| `render`    | `ReactElement \| ((props, state) => ReactElement)` | -       | Replace the underlying element, or compose it with another component. |
| `children`  | `ReactNode`                                                        | -       | The status message.                                                   |
| `className` | `string`                                                           | -       | Extra classes, merged via `tailwind-merge`.                           |

### CommandPaletteGroup [#commandpalettegroup]

Wraps one labeled section of a grouped list.

| Prop        | Type                                                               | Default | Description                                                              |
| ----------- | ------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------ |
| `items`     | `readonly T[]`                                                     | -       | The group's items, so the inner `CommandPaletteCollection` can map them. |
| `render`    | `ReactElement \| ((props, state) => ReactElement)` | -       | Replace the underlying element, or compose it with another component.    |
| `className` | `string`                                                           | -       | Extra classes, merged via `tailwind-merge`.                              |

### CommandPaletteLabel [#commandpalettelabel]

The visible label for a `CommandPaletteGroup`.

| Prop        | Type                                                               | Default | Description                                                           |
| ----------- | ------------------------------------------------------------------ | ------- | --------------------------------------------------------------------- |
| `render`    | `ReactElement \| ((props, state) => ReactElement)` | -       | Replace the underlying element, or compose it with another component. |
| `children`  | `ReactNode`                                                        | -       | The label text.                                                       |
| `className` | `string`                                                           | -       | Extra classes, merged via `tailwind-merge`.                           |

### CommandPaletteCollection [#commandpalettecollection]

Renders the items inside a `CommandPaletteGroup`.

| Prop       | Type  | Default | Description                                                           |
| ---------- | -------------------------------------------- | ------- | --------------------------------------------------------------------- |
| `children` | `(item, index) => ReactNode` | -       | Render function for each item - `(item) => <CommandPaletteItem … />`. |

### CommandPaletteSeparator [#commandpaletteseparator]

A thin divider between sections.

| Prop          | Type                                                               | Default        | Description                                                           |
| ------------- | ------------------------------------------------------------------ | -------------- | --------------------------------------------------------------------- |
| `render`      | `ReactElement \| ((props, state) => ReactElement)` | -              | Replace the underlying element, or compose it with another component. |
| `orientation` | `'horizontal' \| 'vertical'`                       | `'horizontal'` | Layout axis.                                                          |
| `className`   | `string`                                                           | -              | Extra classes, merged via `tailwind-merge`.                           |

### CommandPaletteFooter [#commandpalettefooter]

A row under the list, usually keyboard hints built from [`Kbd`](/ui/components/react/kbd).

| Prop        | Type        | Default | Description                                 |
| ----------- | ----------- | ------- | ------------------------------------------- |
| `children`  | `ReactNode` | -       | The footer content.                         |
| `className` | `string`    | -       | Extra classes, merged via `tailwind-merge`. |

## Accessibility [#accessibility]

- `CommandPaletteContent` is a modal dialog named by `label`, which is rendered as a visually hidden title. Focus moves to the input when it opens and is trapped inside until it closes.
- The input has `role="combobox"` and controls a `listbox` of `option`s through `aria-activedescendant`, so focus stays in the field while the highlight moves.
- **↑/↓** move the highlight, **Enter** runs the highlighted item, **Escape** closes the palette, and typing filters the list. `shortcut` toggles it from anywhere on the page.
- The first match is always highlighted, so Enter runs it without a separate keystroke.
- A toggle item that stays open should announce its state with `aria-checked`, as in [Keep it open](#keep-it-open).
- Enter and exit transitions are skipped when the user prefers reduced motion.
