{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"command-palette","type":"registry:component","title":"Command palette","description":"⌘K that grows out of the search pill: fuzzy search, nested lists, and commands that run in place.","author":"Hairline UI","dependencies":[],"registryDependencies":["https://hairlineui.com/r/text-morph.json"],"files":[{"path":"registry/command-palette.tsx","type":"registry:component","content":"\"use client\";\n\nimport * as React from \"react\";\nimport { createPortal } from \"react-dom\";\nimport { TextMorph } from \"./text-morph\";\n\n/* ─────────────────────────────────────────────────────────\n * COMMAND PALETTE: ⌘K, from the pill that was always there\n *\n * closed a quiet \"Search… ⌘K\" pill\n * opening the pill itself lifts and grows into the palette:\n * position, size and corners ease from pill to panel\n * while its placeholder becomes the field's\n * search results narrow as you type, the letters that match\n * are marked, the panel's height eases to fit and a\n * highlight glides between rows\n * nested \"Change theme…\" opens its own list in place: it\n * slides in from the right as a chip joins the field;\n * Backspace slides back\n * running a command's shortcut blurs into a spinner, then a\n * check that draws itself, and the palette folds back\n * into the pill\n * empty \"No results for “xyz”\", morphing as you type\n *\n * A real dialog: focus moves in and back, arrow keys, Home/End,\n * Enter, Escape (back, then close) and the hotkey to toggle.\n * ───────────────────────────────────────────────────────── */\n\nexport interface CommandItem {\n id: string;\n label: string;\n /** Rows are grouped under this heading, in the order groups first appear. */\n group?: string;\n icon?: React.ReactNode;\n /** Shown on the right, e.g. [\"⌘\", \"N\"]. */\n shortcut?: string[];\n /** Other words that should find it, e.g. [\"dark\", \"light\"] for \"Change theme\". */\n keywords?: string[];\n description?: string;\n /** Navigate here when chosen. */\n href?: string;\n /** Run it. Return a promise to show progress on the row before the palette closes. */\n onSelect?: () => void | Promise;\n /** A nested list, opened in place (e.g. \"Change theme…\"). */\n items?: CommandItem[];\n}\n\nexport interface CommandPaletteProps extends Omit, \"onSelect\"> {\n items: CommandItem[];\n placeholder?: string;\n /** The letter that opens it with ⌘ (or Ctrl). Empty string turns the hotkey off. */\n hotkey?: string;\n open?: boolean;\n defaultOpen?: boolean;\n onOpenChange?: (open: boolean) => void;\n /** Show the \"Search… ⌘K\" pill. Without it, open with the hotkey or the open prop. */\n showTrigger?: boolean;\n /** The pill's words. */\n triggerLabel?: string;\n}\n\ntype Phase = \"closed\" | \"opening\" | \"open\" | \"closing\";\ntype Page = { title: string; items: CommandItem[] };\ntype Row = { item: CommandItem; marks: number[]; score: number };\ntype Rect = { left: number; top: number; width: number; height: number; radius: number };\ntype RunState = { id: string; state: \"pending\" | \"done\" | \"error\" };\n\nconst EASE = \"cubic-bezier(0.16,1,0.3,1)\";\nconst DURATION = 440;\nconst WIDTH = 580;\nconst ROW = 40;\nconst LIST_MAX = 352;\nconst FOCUS = \"focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/40 focus-visible:ring-offset-2 focus-visible:ring-offset-background\";\n\nconst reducedQuery = \"(prefers-reduced-motion: reduce)\";\nconst subscribeReduced = (onChange: () => void) => {\n const query = window.matchMedia(reducedQuery);\n query.addEventListener(\"change\", onChange);\n return () => query.removeEventListener(\"change\", onChange);\n};\nconst useReducedMotion = () =>\n React.useSyncExternalStore(subscribeReduced, () => window.matchMedia(reducedQuery).matches, () => false);\n\n/** Icons trade places through a blur: the old one shrinks away as the new one grows in. */\nconst swap = (on: boolean, reduced: boolean): React.CSSProperties => ({\n opacity: on ? 1 : 0,\n transform: on ? \"none\" : \"scale(0.6)\",\n filter: on ? \"none\" : \"blur(3px)\",\n transition: reduced ? \"none\" : `opacity 220ms ${EASE}, transform 340ms ${EASE}, filter 220ms ${EASE}`,\n});\n\n/** Where the query's letters land in the text: one run if it's there whole, otherwise in order. */\nfunction match(text: string, query: string): number[] | null {\n const t = text.toLowerCase();\n const q = query.toLowerCase().replace(/\\s+/g, \" \").trim();\n if (!q) return [];\n const at = t.indexOf(q);\n if (at >= 0) return Array.from({ length: q.length }, (_, i) => at + i);\n const marks: number[] = [];\n let j = 0;\n for (let i = 0; i < t.length && j < q.length; i++) {\n if (q[j] === \" \") j++;\n if (t[i] === q[j]) {\n marks.push(i);\n j++;\n }\n }\n return j >= q.length ? marks : null;\n}\n\nfunction rank(items: CommandItem[], query: string): Row[] {\n const q = query.trim();\n if (!q) return items.map((item) => ({ item, marks: [], score: 0 }));\n const rows: Row[] = [];\n for (const item of items) {\n const marks = match(item.label, q);\n if (marks) {\n const contiguous = marks.length > 1 && marks[marks.length - 1] - marks[0] === marks.length - 1;\n const start = marks[0] ?? 0;\n const wordStart = start === 0 || item.label[start - 1] === \" \";\n const score = (contiguous ? 60 : 30) + (start === 0 ? 40 : wordStart ? 20 : 0) - (marks[marks.length - 1] - start) * 0.5;\n rows.push({ item, marks, score });\n } else if (item.keywords?.some((k) => match(k, q)) || (item.description && match(item.description, q))) {\n rows.push({ item, marks: [], score: 10 });\n }\n }\n return rows.sort((a, b) => b.score - a.score);\n}\n\nfunction Marked({ text, marks }: { text: string; marks: number[] }) {\n if (!marks.length) return <>{text};\n const set = new Set(marks);\n return (\n <>\n {Array.from(text).map((ch, i) =>\n set.has(i) ? (\n \n {ch}\n \n ) : (\n {ch}\n )\n )}\n \n );\n}\n\nfunction Kbd({ children }: { children: React.ReactNode }) {\n return (\n \n {children}\n \n );\n}\n\nfunction SearchIcon({ className = \"\" }: { className?: string }) {\n return (\n \n \n \n \n );\n}\n\nfunction Check({ drawn, reduced }: { drawn: boolean; reduced: boolean }) {\n return (\n \n \n \n );\n}\n\n/** One page of results. Kept as its own piece so the page you leave can slide out while the next slides in. */\nfunction Results({\n rows,\n active,\n run,\n reduced,\n listId,\n optionId,\n setActive,\n choose,\n rowRefs,\n}: {\n rows: Row[];\n active: number;\n run: RunState | null;\n reduced: boolean;\n listId?: string;\n optionId?: (i: number) => string;\n setActive?: (i: number) => void;\n choose?: (i: number) => void;\n rowRefs?: React.MutableRefObject<(HTMLDivElement | null)[]>;\n}) {\n let lastGroup: string | undefined;\n return (\n
\n {rows.map((row, i) => {\n const { item } = row;\n const heading = item.group && item.group !== lastGroup ? item.group : null;\n lastGroup = item.group;\n const running = run?.id === item.id;\n const state = running ? run.state : null;\n return (\n \n {heading && (\n
\n {heading}\n
\n )}\n {\n if (rowRefs) rowRefs.current[i] = el;\n }}\n id={optionId?.(i)}\n role=\"option\"\n aria-selected={i === active}\n aria-disabled={Boolean(run) || undefined}\n onPointerMove={() => i !== active && setActive?.(i)}\n onClick={() => choose?.(i)}\n className=\"relative flex cursor-pointer items-center gap-3 rounded-xl px-3 text-[13.5px] text-foreground/80\"\n style={{ height: ROW }}\n >\n {item.icon && (\n \n {item.icon}\n \n )}\n \n \n {item.items && …}\n \n {item.description && {item.description}}\n {/* The right edge: shortcut or chevron, which blurs into a spinner and then a check while it runs. */}\n \n \n {item.items ? (\n \n \n \n ) : (\n item.shortcut?.map((k) => {k})\n )}\n \n \n \n \n \n \n \n \n
\n \n );\n })}\n \n );\n}\n\nexport function CommandPalette({\n items,\n placeholder = \"Search or jump to…\",\n hotkey = \"k\",\n open: openProp,\n defaultOpen = false,\n onOpenChange,\n showTrigger = true,\n triggerLabel = \"Search…\",\n className = \"\",\n ...props\n}: CommandPaletteProps) {\n const reduced = useReducedMotion();\n const id = React.useId();\n const [phase, setPhase] = React.useState(defaultOpen ? \"open\" : \"closed\");\n const [query, setQuery] = React.useState(\"\");\n const [stack, setStack] = React.useState([]);\n const [active, setActive] = React.useState(0);\n const [run, setRun] = React.useState(null);\n const [from, setFrom] = React.useState(null);\n const [listHeight, setListHeight] = React.useState(0);\n const [highlight, setHighlight] = React.useState({ top: 0, ready: false });\n const [leaving, setLeaving] = React.useState<{ key: number; rows: Row[]; active: number; dir: number }[]>([]);\n const [enterDir, setEnterDir] = React.useState(0);\n const [mac, setMac] = React.useState(true);\n const [portal, setPortal] = React.useState(null);\n\n const triggerRef = React.useRef(null);\n const inputRef = React.useRef(null);\n const listRef = React.useRef(null);\n const innerRef = React.useRef(null);\n const paneRef = React.useRef(null);\n const rowRefs = React.useRef<(HTMLDivElement | null)[]>([]);\n const returnFocus = React.useRef(null);\n const timer = React.useRef(0);\n const leaveKey = React.useRef(0);\n\n const isOpen = phase === \"open\";\n const mounted = phase !== \"closed\";\n const page = stack[stack.length - 1];\n const pageItems = page ? page.items : items;\n const rows = React.useMemo(() => rank(pageItems, query), [pageItems, query]);\n\n React.useEffect(() => {\n setPortal(document.body);\n setMac(/Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent));\n }, []);\n\n // Where the pill is, so the palette can grow out of it (and fold back into it).\n const pillRect = (): Rect | null => {\n const el = triggerRef.current;\n if (!el || !showTrigger) return null;\n const r = el.getBoundingClientRect();\n // Off screen, or hidden (a pill tucked away on narrow screens has no box): open in place instead.\n if (!r.width || r.bottom < 0 || r.top > window.innerHeight) return null;\n return { left: r.left, top: r.top, width: r.width, height: r.height, radius: r.height / 2 };\n };\n\n const target = (): Rect => {\n const vw = document.documentElement.clientWidth;\n const width = Math.min(WIDTH, vw - 24);\n return { left: (vw - width) / 2, top: Math.max(48, Math.round(window.innerHeight * 0.16)), width, height: 0, radius: 20 };\n };\n\n const setOpen = React.useCallback(\n (next: boolean) => {\n if (openProp === undefined) {\n window.clearTimeout(timer.current);\n if (next) {\n returnFocus.current = document.activeElement as HTMLElement | null;\n setFrom(pillRect());\n setPhase(reduced ? \"open\" : \"opening\");\n } else {\n setFrom(pillRect());\n if (reduced) setPhase(\"closed\");\n else {\n setPhase(\"closing\");\n timer.current = window.setTimeout(() => setPhase(\"closed\"), DURATION);\n }\n const back = returnFocus.current;\n requestAnimationFrame(() => (back && document.contains(back) ? back : triggerRef.current)?.focus({ preventScroll: true }));\n }\n }\n onOpenChange?.(next);\n },\n // eslint-disable-next-line react-hooks/exhaustive-deps\n [openProp, onOpenChange, reduced, showTrigger]\n );\n\n // Controlled: follow the prop through the same phases.\n React.useEffect(() => {\n if (openProp === undefined) return;\n window.clearTimeout(timer.current);\n if (openProp && (phase === \"closed\" || phase === \"closing\")) {\n returnFocus.current = document.activeElement as HTMLElement | null;\n setFrom(pillRect());\n setPhase(reduced ? \"open\" : \"opening\");\n } else if (!openProp && (phase === \"open\" || phase === \"opening\")) {\n setFrom(pillRect());\n if (reduced) setPhase(\"closed\");\n else {\n setPhase(\"closing\");\n timer.current = window.setTimeout(() => setPhase(\"closed\"), DURATION);\n }\n }\n // eslint-disable-next-line react-hooks/exhaustive-deps\n }, [openProp]);\n\n // Paint at the pill's size first, then let it grow.\n React.useEffect(() => {\n if (phase !== \"opening\") return;\n let inner = 0;\n const outer = requestAnimationFrame(() => (inner = requestAnimationFrame(() => setPhase(\"open\"))));\n return () => {\n cancelAnimationFrame(outer);\n cancelAnimationFrame(inner);\n };\n }, [phase]);\n\n // A fresh start each time it opens.\n React.useEffect(() => {\n if (phase !== \"opening\" && !(phase === \"open\" && reduced)) return;\n setQuery(\"\");\n setStack([]);\n setActive(0);\n setRun(null);\n setLeaving([]);\n setHighlight({ top: 0, ready: false });\n }, [phase, reduced]);\n\n React.useEffect(() => {\n if (isOpen) inputRef.current?.focus({ preventScroll: true });\n }, [isOpen]);\n\n React.useEffect(() => () => window.clearTimeout(timer.current), []);\n\n // The hotkey, from anywhere on the page.\n React.useEffect(() => {\n if (!hotkey) return;\n const onKey = (e: KeyboardEvent) => {\n if (e.key.toLowerCase() !== hotkey.toLowerCase() || !(e.metaKey || e.ctrlKey) || e.altKey || e.shiftKey) return;\n e.preventDefault();\n setOpen(!(phase === \"open\" || phase === \"opening\"));\n };\n document.addEventListener(\"keydown\", onKey);\n return () => document.removeEventListener(\"keydown\", onKey);\n }, [hotkey, phase, setOpen]);\n\n // The page behind stays where it is.\n React.useEffect(() => {\n if (!mounted) return;\n const html = document.documentElement;\n const gap = window.innerWidth - html.clientWidth;\n const before = { overflow: html.style.overflow, paddingRight: html.style.paddingRight };\n html.style.overflow = \"hidden\";\n if (gap > 0) html.style.paddingRight = `${gap}px`;\n return () => {\n html.style.overflow = before.overflow;\n html.style.paddingRight = before.paddingRight;\n };\n }, [mounted]);\n\n // The list's height, so the panel can ease to fit the results.\n React.useLayoutEffect(() => {\n const el = innerRef.current;\n if (!el) return;\n const measure = () => setListHeight((h) => (h === el.offsetHeight ? h : el.offsetHeight));\n measure();\n const observer = new ResizeObserver(measure);\n observer.observe(el);\n return () => observer.disconnect();\n }, [mounted]);\n\n // Keep the active row in range as the results change.\n React.useEffect(() => {\n setActive((a) => Math.min(a, Math.max(0, rows.length - 1)));\n }, [rows.length]);\n\n // The highlight glides to the active row; the list scrolls only as far as it must.\n React.useLayoutEffect(() => {\n const row = rowRefs.current[active];\n const list = listRef.current;\n if (!row || !list) return;\n const top = row.offsetTop;\n setHighlight((h) => (h.top === top && h.ready ? h : { top, ready: h.ready || isOpen }));\n if (top < list.scrollTop) list.scrollTop = top - 4;\n else if (top + ROW > list.scrollTop + list.clientHeight) list.scrollTop = top + ROW - list.clientHeight + 4;\n }, [active, rows, isOpen]);\n\n // A new page slides in from the side you went.\n React.useLayoutEffect(() => {\n if (!enterDir || reduced) return;\n paneRef.current?.animate(\n [\n { opacity: 0, filter: \"blur(4px)\", transform: `translateX(${enterDir * 28}px)` },\n { opacity: 1, filter: \"blur(0px)\", transform: \"none\" },\n ],\n { duration: 360, easing: EASE, delay: 40, fill: \"backwards\" }\n );\n }, [stack.length, enterDir, reduced]);\n\n React.useEffect(() => {\n if (!leaving.length) return;\n const t = window.setTimeout(() => setLeaving([]), 260);\n return () => window.clearTimeout(t);\n }, [leaving]);\n\n const go = (dir: 1 | -1, next: Page[]) => {\n if (!reduced) setLeaving((l) => [...l, { key: ++leaveKey.current, rows, active, dir }]);\n setEnterDir(dir);\n setStack(next);\n setQuery(\"\");\n setActive(0);\n setHighlight((h) => ({ ...h, ready: false }));\n };\n\n const choose = async (i: number) => {\n const row = rows[i];\n if (!row || run) return;\n const { item } = row;\n setActive(i);\n if (item.items) return go(1, [...stack, { title: item.label.replace(/…$/, \"\"), items: item.items }]);\n if (item.href && !item.onSelect) {\n setOpen(false);\n window.location.assign(item.href);\n return;\n }\n const result = item.onSelect?.();\n if (!(result instanceof Promise)) return setOpen(false);\n setRun({ id: item.id, state: \"pending\" });\n try {\n await result;\n setRun({ id: item.id, state: \"done\" });\n timer.current = window.setTimeout(() => setOpen(false), reduced ? 0 : 520);\n } catch {\n setRun(null);\n rowRefs.current[i]?.animate(\n [{ transform: \"none\" }, { transform: \"translateX(-4px)\" }, { transform: \"translateX(4px)\" }, { transform: \"translateX(-2px)\" }, { transform: \"none\" }],\n { duration: 380, easing: \"ease-out\" }\n );\n }\n };\n\n const onKeyDown = (e: React.KeyboardEvent) => {\n if (e.nativeEvent.isComposing) return;\n const moves: Record = { ArrowDown: active + 1, ArrowUp: active - 1, Home: 0, End: rows.length - 1 };\n if (e.key in moves && rows.length) {\n if ((e.key === \"Home\" || e.key === \"End\") && query) return;\n e.preventDefault();\n setActive((moves[e.key] + rows.length) % rows.length);\n } else if (e.key === \"Enter\") {\n e.preventDefault();\n choose(active);\n } else if (e.key === \"Escape\") {\n e.preventDefault();\n if (query) setQuery(\"\");\n else if (stack.length) go(-1, stack.slice(0, -1));\n else setOpen(false);\n } else if (e.key === \"Backspace\" && !query && stack.length) {\n e.preventDefault();\n go(-1, stack.slice(0, -1));\n } else if (e.key === \"Tab\") {\n // Focus stays in the field; the list is reached with the arrows.\n e.preventDefault();\n }\n };\n\n const final = mounted ? target() : null;\n const shape = isOpen || !from ? final : from;\n const listVisible = Math.min(listHeight, LIST_MAX);\n const panelHeight = 52 + (listVisible ? listVisible + 12 : 0) + 37;\n const empty = rows.length === 0;\n const kbd = mac ? \"⌘\" : \"Ctrl\";\n\n const panel =\n mounted && final && shape ? (\n
\n {/* A faint veil over the page; clicking it closes. */}\n setOpen(false)}\n className=\"absolute inset-0 bg-background/55\"\n style={{ opacity: isOpen ? 1 : 0, transition: reduced ? \"none\" : `opacity ${DURATION}ms ${EASE}` }}\n />\n \n {/* The pill's words, fading as the panel grows out of it. */}\n {from && (\n \n \n {triggerLabel}\n \n )}\n\n \n
\n \n {/* Where you are, as a chip that opens in when you go into a list. */}\n \n \n \n {page?.title ?? \"\"}\n \n \n \n {\n setQuery(e.target.value);\n setActive(0);\n }}\n placeholder={page ? `Search ${page.title.toLowerCase()}…` : placeholder}\n role=\"combobox\"\n aria-expanded=\"true\"\n aria-controls={`${id}-list`}\n aria-activedescendant={rows.length ? `${id}-opt-${active}` : undefined}\n aria-autocomplete=\"list\"\n spellCheck={false}\n className=\"h-full min-w-0 flex-1 bg-transparent text-[14.5px] text-foreground outline-none placeholder:text-muted-foreground\"\n />\n esc\n
\n\n \n
\n {!empty && (\n \n )}\n {leaving.map((l) => (\n \n \n \n ))}\n
\n `${id}-opt-${i}`}\n setActive={(i) => !run && setActive(i)}\n choose={choose}\n rowRefs={rowRefs}\n />\n
\n {empty && (\n

\n {query ? `No results for “${query.trim()}”` : \"Nothing here yet\"}\n

\n )}\n
\n
\n\n
\n \n ↑\n ↓\n to move\n \n \n ↵\n to open\n \n \n \n ⌫\n to go back\n \n \n
\n \n \n \n ) : null;\n\n return (\n
\n {showTrigger && (\n setOpen(true)}\n className={`group inline-flex h-9 items-center gap-2 rounded-full bg-background pl-3 pr-1.5 text-[13px] text-muted-foreground shadow-[inset_0_0_0_1px_var(--border)] transition-[box-shadow,color] duration-300 hover:text-foreground hover:shadow-[inset_0_0_0_1px_color-mix(in_oklab,var(--foreground)_22%,transparent)] ${FOCUS}`}\n style={{ opacity: mounted ? 0 : 1, transition: mounted || reduced ? \"none\" : \"opacity 160ms ease-out\" }}\n >\n \n {triggerLabel}\n \n {kbd}\n {hotkey.toUpperCase()}\n \n \n )}\n {portal && panel ? createPortal(panel, portal) : null}\n
\n );\n}\n\n/** The page you left: it slides out toward the side you came from, then removes itself. */\nfunction LeavingPane({ dir, children }: { dir: number; children: React.ReactNode }) {\n const ref = React.useRef(null);\n React.useLayoutEffect(() => {\n const animation = ref.current?.animate(\n [\n { opacity: 1, filter: \"blur(0px)\", transform: \"none\" },\n { opacity: 0, filter: \"blur(4px)\", transform: `translateX(${-dir * 28}px)` },\n ],\n { duration: 240, easing: EASE, fill: \"forwards\" }\n );\n return () => animation?.cancel();\n }, [dir]);\n return (\n
\n {children}\n
\n );\n}\n"}],"css":{},"docs":"Docs and live preview: https://hairlineui.com/ui/command-palette"}