CommandPalette

Alpha

An 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

CommandPalette component props
PropTypeDefaultDescription
openboolean-Controlled open state
onOpenChange(open: boolean) => void-Called when open state changes
placeholderstring'Type a command...'Search input placeholder

Sub-components

CommandPalette.Input

CommandPalette.Input props
PropTypeDefaultDescription
placeholderstring-Input placeholder

CommandPalette.List

CommandPalette.List props
PropTypeDefaultDescription
children*ReactNode-Command items

CommandPalette.Group

CommandPalette.Group props
PropTypeDefaultDescription
headingstring-Group heading

CommandPalette.Item

CommandPalette.Item props
PropTypeDefaultDescription
onSelect() => void-Called when item is selected
children*ReactNode-Item content

CommandPalette.Empty

CommandPalette.Empty props
PropTypeDefaultDescription
childrenReactNode-Empty state content

Keyboard Interactions

Accessibility
All keyboard interactions follow WAI-ARIA best practices and work without any additional configuration.
Keyboard shortcuts for CommandPalette
KeyAction
Ctrl+K / Cmd+KOpens the command palette (configurable)
ArrowDown / ArrowUpNavigate between items
EnterExecute the focused command
EscapeClose the palette