@mshafiqyajid/react-command-palette
⌘K command palette for React. Headless hook + styled component. Fuzzy match against label/hint/keywords, item grouping, recent-items section, full keyboard navigation, configurable global hotkey (⌘K / Ctrl+K). Zero dependencies, fully typed.
Playground #
Props
TSX
import { CommandPaletteStyled } from "@mshafiqyajid/react-command-palette/styled";
import "@mshafiqyajid/react-command-palette/styles.css";
<CommandPaletteStyled
items={items}
open={open}
onOpenChange={setOpen}
onSelect={(item) => /* … */}
withRecent
withFooter
/>Install #
npm install @mshafiqyajid/react-command-paletteQuick start #
import { CommandPaletteStyled } from "@mshafiqyajid/react-command-palette/styled";
import "@mshafiqyajid/react-command-palette/styles.css";
const items = [
{ id: "new", label: "New file", group: "File", shortcut: "⌘N" },
{ id: "open", label: "Open recent", group: "File", keywords: ["history"] },
{ id: "find", label: "Find in files", group: "Edit", shortcut: "⌘F" },
{ id: "settings", label: "Open settings", group: "App" },
];
<CommandPaletteStyled
items={items}
onSelect={(item) => console.log(item.id)}
recentStorageKey="my-app-cmd-recent"
/>Opens automatically on ⌘K / Ctrl+K. Up/Down moves, Enter selects, Esc closes.
Headless #
import { useCommandPalette } from "@mshafiqyajid/react-command-palette";
const cmd = useCommandPalette({ items, onSelect });
return cmd.isOpen ? (
<div role="dialog">
<input {...cmd.inputProps} placeholder="Type a command…" />
<ul {...cmd.listProps}>
{cmd.groups.map((g) => (
<section key={g.id}>
<h4>{g.label}</h4>
{g.items.map((item) => (
<li key={item.id} {...cmd.getItemProps(item)}>{item.label}</li>
))}
</section>
))}
</ul>
</div>
) : null;API #
| Prop | Type | Default | Description |
|---|---|---|---|
| items | CommandItem[] | — | Required. Items to render. |
| onSelect | (item) => void | — | Fires on Enter / click |
| defaultOpen / open / onOpenChange | boolean | false | Open state (uncontrolled or controlled) |
| defaultQuery | string | "" | Initial search value |
| filter | (item, q) => boolean | substring match | Custom filter (fuzzy/score) |
| recentStorageKey | string | — | Persists last 5 selections via localStorage |
| hotkey | { key, meta?, ctrl?, shift? } | null | { key: "k", meta: true, ctrl: true } | Global open shortcut |
| placeholder | string | "Type a command…" | Search input placeholder |
| emptyText | ReactNode | "No results." | Shown when no items match |
| emptyState | (query) => ReactNode | — | Custom empty state — receives the active query. Overrides emptyText. |
| loading | boolean | false | Show a loading row instead of items (use with async filtering) |
| loadingText | ReactNode | "Loading…" | Loading row text |
| highlightMatches | boolean | true | Bolden matched query characters in labels |
| footer | ReactNode | — | Footer slot (keyboard hints, etc) |
CommandItem #
| Field | Type | Description |
|---|---|---|
| id | string | Required, unique |
| label | string | Required, matched by filter |
| hint | string? | Secondary text + matched by filter |
| icon | ReactNode? | Left-side icon |
| shortcut | string? | Right-side keyboard hint |
| group | string? | Section heading |
| disabled | boolean? | Skipped by keyboard nav |
| keywords | string[]? | Extra search terms |
| data | T? | Free-form payload |