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.
\n| Feature | \nImplementation | \n
|---|---|
| Arrow navigation | \nTrack selectedIndex, clamp with Math.min/max | \n
| Keep in view | \nscrollIntoView({ block: 'nearest', behavior: 'smooth' }) | \n
| Shortcut matching | \nStrip spaces from shortcuts, match against query | \n
| Stable icons | \nDefine icon elements outside component | \n
| Stable handlers | \nuseCallback + noop constant for disabled states | \n
This is the most common source of bugs. The keyboard effect must ONLY run when the palette is open. Use a wrapper component:
\n// Wrapper ensures effects only run when open\nexport function CommandPalette(props: CommandPaletteProps) {\n if (!props.isOpen) return null;\n return <CommandPaletteContent {...props} />;\n}\n\n// Content component - effects run on mount/unmount\nfunction CommandPaletteContent({ onClose, ... }: CommandPaletteProps) {\n // Effects here only run when palette is visible\n useEffect(() => {\n const handleKeyDown = (e: KeyboardEvent) => { ... };\n window.addEventListener('keydown', handleKeyDown);\n return () => window.removeEventListener('keydown', handleKeyDown);\n }, [deps]);\n\n return <div>...</div>;\n}\nWhy this matters:
\nif (!isOpen) return null AFTER useEffect hooks, the effects still run when closedThe input MUST be focused (for typing to work), and keyboard navigation MUST use window.addEventListener. This works because:
e.preventDefault() just stops page scrolling// Input with autoFocus - NOT setTimeout focus\n<input\n autoFocus\n type=\"text\"\n value={query}\n onChange={(e) => {\n setQuery(e.target.value);\n setSelectedIndex(0); // Reset to first item when query changes\n }}\n/>\nconst [selectedIndex, setSelectedIndex] = useState(0);\n\nuseEffect(() => {\n if (!isOpen) return;\n\n const handleKeyDown = (e: KeyboardEvent) => {\n switch (e.key) {\n case 'ArrowDown':\n e.preventDefault();\n // Clamp to last item\n setSelectedIndex((prev) => Math.min(prev + 1, filteredItems.length - 1));\n break;\n case 'ArrowUp':\n e.preventDefault();\n // Clamp to first item\n setSelectedIndex((prev) => Math.max(prev - 1, 0));\n break;\n case 'Enter':\n e.preventDefault();\n if (filteredItems[selectedIndex]) {\n executeCommand(filteredItems[selectedIndex]);\n close();\n }\n break;\n case 'Escape':\n e.preventDefault();\n close();\n break;\n }\n };\n\n // NO capture phase needed - simple window listener works with focused input\n window.addEventListener('keydown', handleKeyDown);\n return () => window.removeEventListener('keydown', handleKeyDown);\n}, [isOpen, filteredItems, selectedIndex, close]);\nKey patterns:
\ne.preventDefault() stops arrow keys from scrolling the pageMath.min/max prevents index going out of boundsfilteredItems so navigation updates when filter changesautoFocus on input, NOT setTimeout(() => ref.current?.focus(), 0)const itemRefs = useRef<(HTMLButtonElement | null)[]>([]);\n\n// Scroll effect - runs when selection changes\nuseEffect(() => {\n const selectedItem = itemRefs.current[selectedIndex];\n if (selectedItem) {\n selectedItem.scrollIntoView({\n block: 'nearest', // Minimal scroll - only scroll if needed\n behavior: 'smooth', // Smooth animation\n });\n }\n}, [selectedIndex]);\n\n// Assign refs in render\n{\n filteredItems.map((item, index) => (\n <button\n key={index}\n ref={(el) => {\n itemRefs.current[index] = el;\n }}\n className={index === selectedIndex ? 'bg-blue-100' : ''}\n >\n {item.label}\n </button>\n ));\n}\nconst selectedItemRef = useRef<HTMLButtonElement>(null);\n\nuseEffect(() => {\n if (isOpen && selectedItemRef.current) {\n selectedItemRef.current.scrollIntoView({\n block: 'nearest',\n behavior: 'smooth',\n });\n }\n}, [isOpen, selectedIndex]);\n\n// Only assign ref to selected item\n<button\n ref={index === selectedIndex ? selectedItemRef : null}\n>\nWhy block: 'nearest'?
'nearest' only scrolls if the element is outside the visible area'center' would scroll even when item is already visible, causing jarring movement'start' or 'end' would always align to top/bottomconst filteredCommands = commands.filter((command) => {\n const q = query.toLowerCase().trim();\n if (!q) return true;\n\n // Standard label matching\n if (command.label.toLowerCase().includes(q)) return true;\n\n // Shortcut matching: \"gd\" matches \"g d\", \"gb\" matches \"g b\"\n if (command.shortcut) {\n const shortcutNoSpaces = command.shortcut.toLowerCase().replace(/\\s+/g, '');\n if (shortcutNoSpaces.startsWith(q) || shortcutNoSpaces.includes(q)) {\n return true;\n }\n }\n\n // For numbered items (PRs, issues), match by number\n if (command.type === 'pr') {\n const numberMatch = q.match(/^#?(\\d+)$/);\n if (numberMatch) {\n return String(command.pr.number).startsWith(numberMatch[1]);\n }\n }\n\n return false;\n});\nWhy strip spaces from shortcuts?\nUsers type continuously without spaces. Shortcut \"g d\" should match when user types \"gd\".
Command palettes often suffer from infinite re-renders when command objects are recreated every render.
\n// BAD: Icons recreated every render\nfunction usePageCommands() {\n const commands = useMemo(\n () => [\n {\n label: 'Sync',\n icon: <RefreshCw size={16} />, // New element every render!\n action: () => onSync(), // New function every render!\n },\n ],\n [onSync]\n ); // Even with deps, icon is new\n\n useRegisterCommands(commands); // Triggers re-registration → re-render loop\n}\n// GOOD: Icons defined OUTSIDE component\nconst refreshIcon = <RefreshCw size={16} />;\nconst refreshSpinIcon = <RefreshCw size={16} className=\"animate-spin\" />;\nconst noop = () => {};\n\nfunction usePageCommands({ onSync, isSyncing }: Props) {\n // Memoize handlers\n const handleSync = useCallback(() => onSync?.(), [onSync]);\n\n const commands = useMemo(\n () => [\n {\n label: isSyncing ? 'Syncing...' : 'Sync',\n icon: isSyncing ? refreshSpinIcon : refreshIcon, // Stable references\n action: isSyncing ? noop : handleSync, // noop, not undefined\n },\n ],\n [isSyncing, handleSync]\n );\n\n useRegisterCommands(commands);\n}\nInstead of comparing object references, compare by labels:
\nexport function useRegisterCommands(commands: CommandItem[]) {\n const { registerCommands, unregisterCommands } = useCommandPalette();\n\n // Create stable ID based on LABELS, not object references\n const commandIds = useMemo(\n () =>\n commands\n .map((c) => {\n if (c.type === 'nav') return `nav:${c.path}`;\n return `action:${c.label}`;\n })\n .sort()\n .join('|'),\n [commands]\n );\n\n const commandsRef = useRef<CommandItem[]>(commands);\n useEffect(() => {\n commandsRef.current = commands;\n });\n\n const prevIdsRef = useRef<string>('');\n\n useEffect(() => {\n // Only register if structure actually changed\n if (commandIds !== prevIdsRef.current) {\n registerCommands(commandsRef.current);\n prevIdsRef.current = commandIds;\n return () => unregisterCommands(commandsRef.current);\n }\n }, [commandIds, registerCommands, unregisterCommands]);\n}\ntype CommandItem =\n | { type: 'action'; label: string; icon?: React.ReactNode; action: () => void; shortcut?: string }\n | { type: 'nav'; label: string; icon?: React.ReactNode; path: string; shortcut?: string }\n | { type: 'file'; file: FileType; label: string; icon?: React.ReactNode }\n | { type: 'pr'; pr: PRType; label: string; icon?: React.ReactNode };\n\n// Execute based on type\nfunction executeCommand(command: CommandItem) {\n switch (command.type) {\n case 'action':\n command.action();\n break;\n case 'nav':\n navigate(command.path);\n break;\n case 'file':\n onFileSelect(command.file);\n break;\n case 'pr':\n navigate(`/repos/${command.owner}/${command.repo}/pulls/${command.pr.number}`);\n break;\n }\n}\n| Mistake | \nWhy It Fails | \nFix | \n
|---|---|---|
| Icons inside useMemo | \nNew icon element every render | \nDefine icons as constants outside component | \n
| Not resetting index on filter | \nArrow keys start from wrong position | \nsetSelectedIndex(0) in onChange | \n
block: 'center' in scrollIntoView | \nJarring scroll when item already visible | \nUse block: 'nearest' | \n
Missing e.preventDefault() | \nArrow keys scroll page AND move selection | \nAdd preventDefault for ArrowUp/Down | \n
| Forgetting cleanup in useEffect | \nEvent listeners accumulate | \nReturn cleanup function | \n
undefined for disabled action | \nType error or click does nothing | \nUse noop constant | \n
Using { capture: true } on window listener | \nNot needed and can cause issues | \nUse simple addEventListener without options | \n
| Focusing a container instead of input | \nTyping won't work, UX feels broken | \nUse autoFocus on input, window listener handles arrows | \n
setTimeout for focus | \nRace conditions, focus may fail | \nUse autoFocus attribute on input | \n
onKeyDown on input element | \nWorks but less reliable than window | \nUse window.addEventListener in useEffect | \n
| Using refs to avoid re-registering listener | \nStale closures, missed updates | \nInclude deps in array, let listener re-register | \n
if (!isOpen) return null after useEffect | \nEffects run even when closed, listener always active | \nUse wrapper component pattern (see above) | \n
bg-transparent with conditional bg-accent-light | \nTailwind CSS conflict - both set background-color, compiled order wins | \nPut background classes in conditional: ${selected ? 'bg-accent-light' : 'bg-transparent hover:bg-gray-100'} | \n