@bw-ui/command-palette
Version:
Beautiful, accessible command palette for the web. Zero dependencies.
199 lines (162 loc) • 6.63 kB
Markdown
# @bw-ui/command-palette
Beautiful, accessible command palette for the web. Zero dependencies.
[Live Demo](https://bw-ui.github.io/bw-command-palette/) • [Documentation](https://github.com/bw-ui/bw-command-palette) • [npm](https://www.npmjs.com/package/@bw-ui/command-palette)
## 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
```bash
npm install @bw-ui/command-palette
```
## Quick Start
```js
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
```html
<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
```js
{
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
```js
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
```js
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
```js
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:
```css
.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