CommandPalette
AlphaAn accessible command palette (Cmd+K / Ctrl+K) for quick actions and search. Combines combobox and listbox patterns in a modal dialog.
Import
import { CommandPalette } from "@compa11y/react";Usage
Example.tsx
import { useState, useEffect } from "react";
import { CommandPalette, Button } from "@compa11y/react";
function AppCommandPalette() {
const [open, setOpen] = useState(false);
useEffect(() => {
const handleKeyDown = (e: KeyboardEvent) => {
if ((e.metaKey || e.ctrlKey) && e.key === "k") {
e.preventDefault();
setOpen(true);
}
};
document.addEventListener("keydown", handleKeyDown);
return () => document.removeEventListener("keydown", handleKeyDown);
}, []);
return (
<>
<Button variant="outline" onClick={() => setOpen(true)}>
Search commands... (Ctrl+K)
</Button>
<CommandPalette open={open} onOpenChange={setOpen}>
<CommandPalette.Input placeholder="Search actions..." />
<CommandPalette.List>
<CommandPalette.Group heading="Navigation">
<CommandPalette.Item onSelect={() => console.log("home")}>
Go to Home
</CommandPalette.Item>
<CommandPalette.Item onSelect={() => console.log("settings")}>
Go to Settings
</CommandPalette.Item>
</CommandPalette.Group>
<CommandPalette.Group heading="Actions">
<CommandPalette.Item onSelect={() => console.log("new")}>
Create New Document
</CommandPalette.Item>
</CommandPalette.Group>
<CommandPalette.Empty>No results found.</CommandPalette.Empty>
</CommandPalette.List>
</CommandPalette>
</>
);
}Features
- Modal overlay with focus trap
- Real-time search filtering
- Grouped commands with separators
- Keyboard shortcut hints per item
- Empty state and loading state
- Compound component API
- Screen reader announcements for results count
Props
| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | - | Controlled open state |
onOpenChange | (open: boolean) => void | - | Called when open state changes |
placeholder | string | 'Type a command...' | Search input placeholder |
Sub-components
CommandPalette.Input
| Prop | Type | Default | Description |
|---|---|---|---|
placeholder | string | - | Input placeholder |
CommandPalette.List
| Prop | Type | Default | Description |
|---|---|---|---|
children* | ReactNode | - | Command items |
CommandPalette.Group
| Prop | Type | Default | Description |
|---|---|---|---|
heading | string | - | Group heading |
CommandPalette.Item
| Prop | Type | Default | Description |
|---|---|---|---|
onSelect | () => void | - | Called when item is selected |
children* | ReactNode | - | Item content |
CommandPalette.Empty
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | - | Empty state content |
Keyboard Interactions
Accessibility
All keyboard interactions follow WAI-ARIA best practices and work without any additional configuration.
| Key | Action |
|---|---|
| Ctrl+K / Cmd+K | Opens the command palette (configurable) |
| ArrowDown / ArrowUp | Navigate between items |
| Enter | Execute the focused command |
| Escape | Close the palette |