Components

Command

A palette that searches and runs grouped commands with shortcuts; in place or in a dialog opened with ⌘K.

Storybook: Storybook
Source: Source

When to use

Command gives quick keyboard access to the app’s pages and actions. CommandDialog opens app-wide with ⌘K or Ctrl+K; Command shows the same list inside a panel.

When not to use

For a choice in a form field: Use Combobox.
For content search: List the results on a separate search page.
As the only way to navigate: The palette is a shortcut; every command should also exist in the interface.

Anatomy

import { Command, Provider, type CommandGroup } from '@bigbang/ui';

const groups: CommandGroup[] = [
  {
    label: 'Pages',
    items: [
      { value: 'home', label: 'Home', icon: 'home', onSelect: () => {} },
      { value: 'settings', label: 'Settings', icon: 'settings', keywords: ['preferences'], onSelect: () => {} },
    ],
  },
  {
    label: 'Actions',
    items: [
      { value: 'new', label: 'Create a new file', icon: 'plus', shortcut: ['⌘', 'N'], onSelect: () => {} },
      { value: 'save', label: 'Save', icon: 'download', shortcut: ['⌘', 'S'], onSelect: () => {} },
      { value: 'theme', label: 'Change theme', icon: 'moon', onSelect: () => {} },
    ],
  },
];

export default function Default() {
  return (
    <Provider locale="en-GB">
      <Command groups={groups} className="max-w-xl" />
    </Provider>
  );
}

Search input: A magnifier icon and an accessible name.
Group heading: Such as “Pages” or “Actions”.
Command: Icon, label and optional shortcut keys.
Empty state: When nothing matches.
Key hints: The keys to move, choose and close; hidden below 640 px.

Behaviour

Typing filters commands on their label and keywords, ignoring case in the Provider’s language; groups left empty are hidden.
The first match is highlighted at once; Enter runs it. Arrow keys move between commands.
Running a command clears the search. In CommandDialog the dialog closes first and focus returns to what opened it.
CommandDialog opens and closes with ⌘K or Ctrl+K; Escape and a click outside close it too.
The dialog rises 8 px, fades and grows in; the backdrop fades. Closing is faster. With reduced motion only the opacity changes.

Guidelines

Keep commands in at most four groups; put the most used ones first.
Show shortcuts only when they are really registered.
Add synonyms with keywords.
Ask for confirmation before running commands that cannot be undone.

Content

Action commands start with a verb: “Create a new file”. Page commands are the page’s name.
Group headings are short noun phrases.

Turkish	English
Komut paleti	Command palette
Komut ya da sayfa arayın	Search commands or pages
gezin	move
seç	choose
kapat	close

Glass

Under a Provider material="glass", CommandDialog turns glass. The inline Command has no surface of its own. material="solid" keeps it solid.

Combobox: Choosing by typing in a form.
Toolbar: Visible, frequent actions.
AppShell: The app frame where the search button that opens the palette sits.