@bw-ui/command-palette

Beautiful, accessible command palette for the web. Zero dependencies.

Live Demo • Documentation • npm

Features

• ⚡ Lightweight — ~6KB gzipped, zero dependencies
• 🔍 Fuzzy Search — Smart matching with scoring and highlighting
• ⌨️ Keyboard First — Full navigation with ↑↓ Enter Escape
• 📱 Responsive — Works beautifully on mobile
• 🎨 Themeable — Light, dark, or system preference
• ♿ Accessible — Full ARIA support, focus trap, screen reader announcements
• 🔄 Nested Commands — Drill-down submenus with breadcrumb navigation
• ⏱️ Async Support — Load commands dynamically
• 📜 Recent History — Remembers frequently used commands

Installation

npm install @bw-ui/command-palette

Quick Start

import { BWCommandPalette } from '@bw-ui/command-palette';
import '@bw-ui/command-palette/css';

const cmd = new BWCommandPalette({
  trigger: 'mod+k',
  commands: [
    {
      id: 'new-file',
      label: 'New File',
      icon: '📄',
      shortcut: 'mod+n',
      action: () => createFile(),
    },
    {
      id: 'settings',
      label: 'Settings',
      icon: '⚙️',
      children: [
        { id: 'theme', label: 'Theme', action: () => openTheme() },
        { id: 'account', label: 'Account', action: () => openAccount() },
      ],
    },
  ],
});

CDN Usage

<link
  rel="stylesheet"
  href="https://unpkg.com/@bw-ui/command-palette/dist/bw-command-palette.min.css"
/>
<script src="https://unpkg.com/@bw-ui/command-palette/dist/bw-command-palette.min.js"></script>

<script>
  const cmd = new BWCommandPalette({
    trigger: 'mod+k',
    commands: [
      { id: 'home', label: 'Go Home', action: () => (location.href = '/') },
    ],
  });
</script>

API

Options

| Option | Type | Default | Description | | --------------------- | ------------------------------- | ---------------------- | --------------------------------- | | trigger | string \| false | 'mod+k' | Hotkey to open (false to disable) | | commands | Command[] \| Function | [] | Commands array or async provider | | placeholder | string | 'Search commands...' | Input placeholder | | emptyMessage | string | 'No commands found' | Empty state message | | closeOnSelect | boolean | true | Close after selecting command | | closeOnClickOutside | boolean | true | Close on backdrop click | | maxResults | number | 50 | Maximum results to show | | debounceMs | number | 150 | Search debounce delay | | rememberRecent | boolean | true | Remember recent commands | | maxRecent | number | 5 | Max recent commands to remember | | theme | 'light' \| 'dark' \| 'system' | 'system' | Color theme | | width | string | '640px' | Dialog width | | maxHeight | string | '420px' | Max dialog height | | zIndex | number | 9999 | CSS z-index |

Command Object

{
  id: 'unique-id',           // Required: unique identifier
  label: 'Command Name',     // Required: display text
  icon: '📄',                // Optional: emoji, HTML, or element
  shortcut: 'mod+n',         // Optional: display-only shortcut hint
  keywords: ['create'],      // Optional: additional search terms
  group: 'File',             // Optional: group header
  description: 'Details',    // Optional: secondary text
  disabled: false,           // Optional: disable selection
  hidden: false,             // Optional: hide from results
  children: [],              // Optional: nested commands
  action: (cmd) => {},       // Optional: callback on select
}

Methods

cmd.open();              // Open palette
cmd.close();             // Close palette
cmd.toggle();            // Toggle open/close

cmd.setCommands([...]);  // Replace all commands
cmd.addCommand({...});   // Add a command
cmd.removeCommand('id'); // Remove by ID

cmd.on('open', () => {});
cmd.on('close', () => {});
cmd.on('select', (command) => {});
cmd.on('query', (query) => {});

cmd.destroy();           // Cleanup

Dynamic Commands

const cmd = new BWCommandPalette({
  commands: async (query) => {
    const results = await fetch(`/api/search?q=${query}`);
    return results.map((item) => ({
      id: item.id,
      label: item.name,
      action: () => navigate(item.url),
    }));
  },
});

Nested Commands

const cmd = new BWCommandPalette({
  commands: [
    {
      id: 'settings',
      label: 'Settings',
      icon: '⚙️',
      children: [
        {
          id: 'appearance',
          label: 'Appearance',
          children: [
            { id: 'light', label: 'Light', action: () => setTheme('light') },
            { id: 'dark', label: 'Dark', action: () => setTheme('dark') },
          ],
        },
      ],
    },
  ],
});

Styling

Customize with CSS variables:

.bw-cmd-root {
  --bw-cmd-bg: #ffffff;
  --bw-cmd-text: #1f2937;
  --bw-cmd-accent: #3b82f6;
  --bw-cmd-border: #e5e7eb;
  --bw-cmd-radius: 16px;
}

Browser Support

Chrome 80+, Firefox 75+, Safari 14+, Edge 80+

License

MIT © Black & White UI Engineering

Black & White UI — Engineered with Precision