CommandPalette

Search and run actions quickly.

Basic usage

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');
            },
          },
        ]}
      />
    </>
  );
}

Async actions

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.',
              );
            },
          },
        ]}
      />
    </>
  );
}

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[]`	—	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) => 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) => void`	—	Called on failure; the palette remains open with error feedback.

Types and interaction

Import the props and data types when creating reusable configuration.

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.

#CommandPalette

#Basic usage

#Async actions

#CommandItem