Build Fast, Accessible React Command Palettes with cmdk

Practical guide: installation, keyboard navigation, searchable menus, examples, and advanced patterns for cmdk in React.

Overview: What cmdk is and when to use it

cmdk is a compact, keyboard-first command menu toolkit for React apps that helps you implement a searchable command palette (think: ⌘K menus) without pulling in heavy UI frameworks. Designed for speed and accessibility, it provides primitives that are unopinionated about styling and state management so you can wire commands, filters, and keyboard shortcuts with minimal fuss.

Use cmdk when your app benefits from fast, global navigation or command execution—searching pages, running quick actions, or connecting deep links. If you want a responsive, a11y-friendly command palette that integrates with your own design system, cmdk is a strong fit.

Below you’ll find concrete installation steps, core APIs, keyboard and accessibility patterns, and advanced techniques such as virtualization, async search, and routing integration. Examples are practical and copy-paste ready so you can get a working command menu in minutes.

Installation & setup: Getting cmdk into a React app

Install cmdk via npm or yarn. It’s a tiny, dependency-free package that plays well with React 17+ and modern bundlers:

npm install cmdk
# or
yarn add cmdk

After installation, create a small provider-centered component that toggles visibility on ⌘/Ctrl+K. The library exposes primitives (Menu, Input, Item, Group) that you compose to build the UI and wire keyboard events. You control styling and layout; cmdk focuses on semantics and keyboard behavior.

For a real quick start, check the official repo and examples: cmdk GitHub. If you’re following a tutorial, this write-up builds on the practical example at Building Command Menus with cmdk.

Core concepts & API: items, groups, filtering, and state

cmdk exposes a minimal API: the Menu root, Input to capture the search string, Item for selectable actions, and Group and Separator for organization. Each Item can hold metadata (id, disabled, shortcut hints) and an onSelect handler. The primitives manage focus, active item, and keyboard wrapping so you can concentrate on commands.

Filtering is usually implemented outside cmdk: keep a stateful list of commands and compute visible items from the Input value. This separation keeps cmdk flexible and lets you implement fuzzy matching, async lookups, or categorized results as needed.

State patterns vary: local state for simple menus, React Context for app-wide command registries, or third-party state managers for complex apps. A common pattern is to register command descriptors (title, category, hotkey, handler) with a small registry; the command palette maps those descriptors to visible Items and calls handlers on selection.

Keyboard navigation & accessibility essentials

Keyboard-first operation is where cmdk shines. Out of the box, arrow keys move focus, Enter selects, and Esc closes the menu. Implementing a global toggle (⌘/Ctrl+K) usually involves a small window-level key listener that sets menuOpen state. Make sure you respect user platform keys: show ⌘K on macOS and Ctrl+K on Windows/Linux using simple user-agent or platform checks.

Accessibility requires proper aria attributes and focus management. cmdk handles much of the focus behavior but you still need to ensure input labeling, announce changes when results update, and provide clear skip/back-to-app behavior. For screen readers, make grouping sensible and avoid exposing raw internal IDs as labels.

Test keyboard flows thoroughly: landing focus on Input when opened, wrapping navigation, handling disabled items, and predictable Escape/blur behavior. Add visible keyboard shortcuts in the item hints so power users can learn time-saving keystrokes.

Example: Minimal searchable command menu

Here’s a compact pattern: maintain an array of command objects and filter them by the input value. Render matching commands as Items. Selecting a command calls its handler (navigate, run a function, open a modal).

// pseudo-code (JSX)

  
  
    {commands.filter(match(query)).map(cmd =>
       run(cmd)}>{cmd.title}
    )}
  

This pattern is intentionally simple and works well for small to medium command sets. For hundreds of commands you’ll want virtualization or server-side search to avoid rendering overhead and janky typing.

For a full, copyable demo, combine the snippet above with the registration pattern in your app root and integrate routing handlers to navigate via commands.

Advanced usage: performance, virtualization, async search, and integrations

Large command sets require tuning. Implementing virtualization (react-window or similar) prevents the DOM from ballooning. For async results—e.g., fuzzy search or remote suggestions—debounce input changes, show skeleton states, and cancel stale requests to avoid race conditions. cmdk itself is agnostic: it renders what you pass it, so offload heavy lifting to a search worker or server.

Integrate cmdk with routing by making commands mirror routes. Commands then call your router (React Router, Next.js router) on selection. You can also serialize command IDs into deep links so users can share “jump to” links for workflows, improving discoverability and automation.

Customization patterns include theming, icon and badge slots on Items, and multi-action rows (e.g., primary action plus secondary dropdown). Because cmdk is unstyled, you can apply your design tokens, animations, or micro-interactions without fighting a framework.

Troubleshooting, best practices, and common pitfalls

Common trap #1: blocking global keys. Window-level key listeners should be respectful: don’t hijack keys when form inputs are focused, and provide an option to disable the global shortcut. Common trap #2: expensive filtering on every keystroke. Debounce or move heavy operations off the main thread.

Keep command descriptors small and serializable. If you attach closures to the registry, ensure handlers remain stable or use refs to avoid unnecessary re-renders. For accessibility, verify that focus returns to the same logical place after the menu closes to preserve context.

Measure perceived speed: small animations and skeleton loaders can make async searches feel snappy even if the server response is slightly delayed. Provide clear empty-state messages and fallback commands when no results match, such as “Create new X” actions based on the query.

Integration patterns: routing, permissions, and telemetry

Map commands to routes by using route metadata to generate command descriptors. This makes the command palette a single source of truth for navigation. For permissioned apps, filter the registry per user role so commands only surface when allowed, and show helpful tooltips for locked commands.

Telemetry benefits: capture events for command opens, selections, and query terms to learn what users search for and where navigation gaps exist. Keep privacy in mind and avoid logging sensitive queries. Aggregated metrics help prioritize featured commands and improve search relevancy.

When using server-side rendering or static generation, hydrate the command registry on the client; avoid server-rendering ephemeral command state. Preserve UX consistency by ensuring the toggle key works after hydration completes.

Semantic core

• Primary: cmdk, cmdk React, cmdk installation, cmdk setup, cmdk tutorial, cmdk example
• Secondary: React command palette, React command menu, React ⌘K menu, React command menu component, React keyboard navigation, React searchable menu
• Clarifying / Long-tail & LSI: React command palette library, cmdk getting started, cmdk advanced usage, React keyboard shortcuts, searchable command palette, command menu accessibility, cmdk virtualization, async search cmdk

Popular user questions (collected)

• How do I install and set up cmdk in a React project?
• How do I implement ⌘K / Ctrl+K global toggle for a command palette?
• How do I add fuzzy or async search to a cmdk menu?
• How do I make cmdk items accessible to screen readers?
• How can I virtualize hundreds of command items in cmdk?
• How to integrate cmdk with React Router or Next.js routing?
• How do I add keyboard shortcuts hints to cmdk items?

FAQ

How do I install and initialize cmdk in a React app?

Install with npm or yarn (npm install cmdk). Import the primitives (Menu, Input, Item, Group) and render a small component that toggles open state on a global key press (⌘/Ctrl+K). Manage your command list in state and map it to Items. Make sure to focus the Input when the menu opens so keyboard users can type immediately.

How can I add fuzzy or async search to the command menu?

Perform filtering outside cmdk: debounce the Input value, then run a fuzzy match (fuse.js, flexsearch) or an async request. Display loading states while awaiting results, and cancel or ignore stale promises to prevent flicker. Render the results as Items; cmdk will handle selection and keyboard navigation.

What are best practices for keyboard navigation and accessibility?

Ensure the Input is focused on open, support arrow keys and Enter for selection, and respect Escape to close. Use semantic grouping and descriptive labels, expose shortcut hints (⌘/Ctrl) visually, and test with screen readers. Avoid trapping focus outside normal app behavior—return focus to the last element when the menu closes.

Further reading and official resources: cmdk GitHub, React documentation, and a practical tutorial at Building Command Menus with cmdk (dev.to).

npm install hamburger-react
# or
yarn add hamburger-react

import React, { useState } from 'react';
import { Sling as Hamburger } from 'hamburger-react'; // pick a variant

export default function MobileNav() {
  const [isOpen, setOpen] = useState(false);

  return (
    <header>
      <nav className="nav-bar">
        <div className="brand">MySite</div>
        <Hamburger toggled={isOpen} toggle={setOpen} size={24} color="#0b3b6f" label="Toggle menu" />
      </nav>

      {isOpen && (
        <div className="mobile-menu">
          <a href="/about">About</a>
          <a href="/work">Work</a>
          <a href="/contact">Contact</a>
        </div>
      )}
    </header>
  );
}