# CommandPalette

> A global ⌘K / Ctrl+K command menu in a dialog for fast navigation and actions.

Category: Advanced · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/command-palette

CommandPalette puts a CommandMenu in a modal dialog that opens from anywhere with a keyboard shortcut. Use it to give power users one place to jump between pages and run common actions. Mount one per app. The examples on this page use hotkey={false} (except the last) so they do not clash with the docs search on ⌘K.

## Import

```tsx
import { CommandPalette, CommandGroup, CommandItem } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { Button, CommandGroup, CommandItem, CommandPalette, Icon } from '@bindshq/stance-react';

export function Basic() {
  return (
    <CommandPalette
      hotkey={false}
      trigger={
        <Button variant="outline" leadingIcon={<Icon name="search" />}>
          Search…
        </Button>
      }
    >
      <CommandGroup heading="Pages">
        <CommandItem value="Dashboard" icon={<Icon name="home" />} />
        <CommandItem value="My templates" icon={<Icon name="file-text" />} />
        <CommandItem value="Org users" icon={<Icon name="users" />} />
        <CommandItem value="Integrations" icon={<Icon name="link" />} />
      </CommandGroup>
    </CommandPalette>
  );
}
```

### Navigation and actions

```tsx
import { Button, CommandGroup, CommandItem, CommandPalette, Icon, toast } from '@bindshq/stance-react';

export function WithActions() {
  return (
    <CommandPalette
      hotkey={false}
      placeholder="Jump to a page or run an action…"
      trigger={<Button leadingIcon={<Icon name="command" />}>Open palette</Button>}
    >
      <CommandGroup heading="Actions">
        <CommandItem
          value="New template"
          keywords={['create']}
          icon={<Icon name="plus" />}
          onSelect={() => toast('Creating a new template…')}
        />
        <CommandItem
          value="Deploy signatures"
          keywords={['publish', 'push']}
          icon={<Icon name="send" />}
          onSelect={() => toast.success('Deployment started')}
        />
        <CommandItem
          value="Toggle theme"
          keywords={['dark', 'light']}
          icon={<Icon name="contrast" />}
        />
      </CommandGroup>
      <CommandGroup heading="Settings">
        <CommandItem value="Billing" icon={<Icon name="credit-card" />} />
        <CommandItem value="Security" icon={<Icon name="shield" />} />
      </CommandGroup>
    </CommandPalette>
  );
}
```

### Custom hotkey

Press ⌘⇧P / Ctrl+Shift+P on this page.

```tsx
import * as React from 'react';
import { Button, CommandGroup, CommandItem, CommandPalette, Icon } from '@bindshq/stance-react';

export function GlobalHotkey() {
  const [open, setOpen] = React.useState(false);
  return (
    <div style={{ display: 'grid', gap: 8, justifyItems: 'center' }}>
      <Button variant="secondary" onClick={() => setOpen(true)}>
        Open (or press ⌘⇧P / Ctrl+Shift+P)
      </Button>
      <CommandPalette
        open={open}
        onOpenChange={setOpen}
        hotkey="mod+shift+p"
        label="Workspace switcher"
      >
        <CommandGroup heading="Workspaces">
          <CommandItem value="Binds Ltd" icon={<Icon name="building" />} />
          <CommandItem value="eSignify Demo" icon={<Icon name="building" />} />
        </CommandGroup>
      </CommandPalette>
    </div>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| CommandPalette | `hotkey` | `string \| false` | `'mod+k'` | Global toggle shortcut; mod is ⌘ on Apple platforms and Ctrl elsewhere. |
| CommandPalette | `open / defaultOpen / onOpenChange` | `boolean / boolean / (open: boolean) => void` | None | Controlled or uncontrolled state. |
| CommandPalette | `trigger` | `ReactElement` | None | Optional button that opens the palette. |
| CommandPalette | `label` | `string` | `'Command palette'` | Dialog title (visually hidden) and input label. |
| CommandPalette | `placeholder` | `string` | None | Input placeholder. |
| CommandPalette | `emptyMessage` | `ReactNode` | `'No results found.'` | Shown when nothing matches. |
| CommandPalette | `closeOnSelect` | `boolean` | `true` | Close after an item runs. |
| CommandPalette | `filter` | `CommandFilter \| false` | None | Custom scorer or disable filtering. |
| CommandPalette | `showFooter` | `boolean` | `true` | Keyboard hints footer (hidden on phones). |
| CommandPalette | `children` | `ReactNode` | None | CommandGroup and CommandItem elements. |

## Accessibility

- A modal dialog with a visually hidden title; focus starts in the search combobox and returns to where it was on close.
- All CommandMenu keyboard behaviour applies inside.
- The shortcut is discoverable through the trigger button and the footer hint; never make the hotkey the only way in.

## Keyboard

| Keys | Action |
| --- | --- |
| `⌘` `K` | Toggle the palette (Ctrl+K on Windows and Linux). |
| `↓` `↑` | Move through results. |
| `Enter` | Run the highlighted command and close. |
| `Esc` | Close. |

## Guidelines

**Do**

- Show the shortcut on a visible trigger, e.g. “Search ⌘K”.
- Group results by type: pages, actions, people.

**Don’t**

- Register several palettes on one page with the same hotkey.

## Related

- https://stanceui.com/components/command-menu
- https://stanceui.com/components/dialog