> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/command-palette.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# CommandPalette

Search and run actions quickly.

## Basic usage


Search commands · Ctrl/Cmd K

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/command-palette/basic.tsx"
import { Button, CommandPalette, useMessage } from '@ifhover/leaf-ui';

import { FilePlus2, Search, Settings } from 'lucide-react';

import { useState } from 'react';

export function CommandPaletteBasic() {
  const [open, setOpen] = useState(false);
  const { message } = useMessage();
  return (
    <>
      <Button startIcon={<Search size={16} />} variant="outline" onClick={() => setOpen(true)}>
        {'Search commands · Ctrl/Cmd K'}
      </Button>
      <CommandPalette
        open={open}
        onOpenChange={setOpen}
        items={[
          {
            key: 'create',
            label: 'Create project',
            icon: <FilePlus2 size={17} />,
            group: 'Project',
            keywords: 'new add',
            onSelect: () => {
              message.success('Project created');
            },
          },
          {
            key: 'settings',
            label: 'Settings',
            icon: <Settings size={17} />,
            group: 'Workspace',
            shortcut: 'G S',
            onSelect: () => {
              message.info('Open settings');
            },
          },
        ]}
      />
    </>
  );
}
```

Expand code

## Async actions


Async action feedback

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/command-palette/basic.tsx"
import { Button, CommandPalette } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function CommandPaletteFailure() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)}>
        {'Async action feedback'}
      </Button>
      <CommandPalette
        shortcut={false}
        open={open}
        onOpenChange={setOpen}
        items={[
          {
            key: 'sync',
            label: 'Sync project',
            onSelect: async () => {
              throw new Error(
                'Connection unavailable. Try again.',
              );
            },
          },
        ]}
      />
    </>
  );
}
```

Expand code

## CommandItem

| Property   | Type                          | Default | Description                              |
| ---------- | ----------------------------- | ------- | ---------------------------------------- |
| `key`      | `string`                      | —       | Required. Stable, unique identifier.     |
| `label`    | `ReactNode`                   | —       | Required. Visible label or content.      |
| `keywords` | `string`                      | —       | Additional search keywords.              |
| `group`    | `ReactNode`                   | —       | Group heading.                           |
| `icon`     | `ReactNode`                   | —       | Icon content.                            |
| `shortcut` | `string`                      | —       | Shortcut hint displayed beside the item. |
| `disabled` | `boolean`                     | —       | Disable interaction.                     |
| `onSelect` | `() => void \| Promise<void>` | —       | Called when an item is selected.         |

## CommandPalette API

| Property       | Type                                                              | Default | Description                                                        |
| -------------- | ----------------------------------------------------------------- | ------- | ------------------------------------------------------------------ |
| `items`        | `readonly `[`CommandItem`](#commanditem)`[]`                      | —       | Required. Items to display.                                        |
| `open`         | `boolean`                                                         | —       | Control whether the panel is open.                                 |
| `defaultOpen`  | `boolean`                                                         | `false` | Initial open state.                                                |
| `onOpenChange` | `(open: boolean) => void`                                         | —       | Called when the panel opens or closes.                             |
| `onSelect`     | `(item: `[`CommandItem`](#commanditem)`) => void`                 | —       | Called when an item is selected.                                   |
| `shortcut`     | `string \| false`                                                 | `'k'`   | Use Ctrl/Cmd with this key to open the palette; false disables it. |
| `placeholder`  | `string`                                                          | —       | Configure placeholder.                                             |
| `loading`      | `boolean`                                                         | —       | Show a loading state.                                              |
| `emptyContent` | `ReactNode`                                                       | —       | Content for an empty collection.                                   |
| `onSearch`     | `(query: string) => void`                                         | —       | Called when the search text changes.                               |
| `onError`      | `(error: unknown, item: `[`CommandItem`](#commanditem)`) => void` | —       | Called on failure; the palette remains open with error feedback.   |

## Types and interaction

Import the props and data types when creating reusable configuration.

```ts
import type { CommandItem, CommandPaletteProps } from '@ifhover/leaf-ui';
```

Provide accessible labels for icon-only actions. Interactive controls support keyboard navigation and respect ConfigProvider themes and reduced motion.