implementing-command-palettes

Implementing Command Palettes

Overview

Command palettes (Cmd+K / Ctrl+K) need precise keyboard navigation, scroll behavior, and stable references to avoid re-render loops. This skill covers the mechanical patterns that make command palettes feel responsive.

When to Use

• Building a Cmd+K command palette in React
• Implementing arrow key navigation with visual selection
• Keeping selected items visible during keyboard navigation
• Filtering commands by label text AND keyboard shortcuts
• Experiencing infinite re-renders when commands update

Quick Reference

Feature	Implementation
Arrow navigation	Track selectedIndex, clamp with Math.min/max
Keep in view	scrollIntoView({ block: 'nearest', behavior: 'smooth' })
Shortcut matching	Strip spaces from shortcuts, match against query
Stable icons	Define icon elements outside component
Stable handlers	useCallback + noop constant for disabled states

Keyboard Navigation

Critical: Wrapper Pattern for Conditional Rendering

This is the most common source of bugs. The keyboard effect must ONLY run when the palette is open. Use a wrapper component:

// Wrapper ensures effects only run when open
export function CommandPalette(props: CommandPaletteProps) {
  if (!props.isOpen) return null;
  return <CommandPaletteContent {...props} />;
}

// Content component - effects run on mount/unmount
function CommandPaletteContent({ onClose, ... }: CommandPaletteProps) {
  // Effects here only run when palette is visible
  useEffect(() => {
    const handleKeyDown = (e: KeyboardEvent) => { ... };
    window.addEventListener('keydown', handleKeyDown);
    return () => window.removeEventListener('keydown', handleKeyDown);
  }, [deps]);

  return <div>...</div>;
}

Why this matters: