cmdk — Fast Unstyled Command Menu for React

Introduction

cmdk is a fast, composable, unstyled command menu component for React. It provides the behavior and accessibility for command palette UIs (the Cmd+K pattern) while leaving all visual styling to you. It powers the command menus in Vercel and other well-known products.

What cmdk Does

• Renders a searchable command list with built-in input filtering
• Groups items with headings and separators for organized menus
• Supports nested pages for multi-level command navigation
• Wraps content in an accessible dialog when using Command.Dialog
• Provides controlled and uncontrolled modes for value and search state

Architecture Overview

cmdk uses React 18 hooks (useId, useSyncExternalStore) to manage an internal store that tracks items, groups, and filtered results. Filtering runs synchronously on each keystroke using a built-in scoring function, though a custom filter can be provided. The component renders a flat list (no virtualization) which performs well up to 2,000-3,000 items.

Self-Hosting & Configuration

• Install via npm: npm install cmdk
• Requires React 18 or later
• Wrap in Command.Dialog for a modal command palette with overlay
• Provide a custom filter prop to override the default fuzzy matching
• Style using the [cmdk-*] CSS selectors exposed on each element

Key Features

• Zero default styles allowing full design control via CSS selectors
• Built-in fuzzy search filtering with customizable scoring
• Accessible with ARIA attributes, keyboard navigation, and screen reader support
• Composable API with Command.Group, Command.Separator, and Command.Empty
• Lightweight with no external dependencies beyond React

Comparison with Similar Tools

• kbar — similar command palette for React; includes its own action registration system and styling
• ninja-keys — web component-based command palette; framework-agnostic but less React-native
• Spotlight (Mantine) — integrated into Mantine UI; coupled to that design system
• Headless UI Command — Tailwind Labs accessibility primitives; different composition model
• Raycast Extensions API — native macOS command palette; not a web component

FAQ

Q: How do I open the menu with a keyboard shortcut? A: Use Command.Dialog and listen for Cmd+K (or Ctrl+K) in a useEffect to toggle the dialog open state.

Q: Can I use it outside of React? A: cmdk is React-specific. For Vue or Svelte, community ports exist, or consider framework-agnostic alternatives like ninja-keys.

Q: Does it support virtualized lists for large datasets? A: No built-in virtualization. Performance is good up to a few thousand items. For larger lists, pair it with a virtualization library.

Q: How do I add icons to command items? A: Place any element (SVG, image, icon component) inside Command.Item as a child alongside the label text.

Sources

• https://github.com/pacocoursey/cmdk
• https://cmdk.paco.me