Navigationv0.1.0

Command Palette

Fuzzy search, grouped results and a spring-driven active row.

Press ⌘J or Ctrl+J, or click the field.

Installation

CLI

npx shadcn@latest add https://hantui-theta.vercel.app/r/command-palette.json

Manual

Install the dependencies

npm install clsx lucide-react motion radix-ui tailwind-merge

Add the shared helpers

Components use cn() from lib/utils.ts and the motion tokens below. See Installation if you have not set them up yet.

lib/motion.ts

import type { Transition, Variants } from "motion/react";

/** Durations in seconds. */
export const duration = {
  instant: 0.1,
  quick: 0.18,
  base: 0.28,
  slow: 0.45,
} as const;

/** Cubic-bezier curves. */
export const ease = {
  /** Entering, UI response. */
  out: [0.22, 1, 0.36, 1],
  /** Moving on screen. */
  inOut: [0.65, 0, 0.35, 1],
  /** Sheets and the mobile menu. */
  drawer: [0.32, 0.72, 0, 1],
} as const;

/** Everyday UI: presses, icon swaps, popovers and modals. Exits run at `exitFactor` of the enter. */
export const ui = {
  press: { scale: 0.96, duration: 0.12 },
  icon: { type: "spring", duration: 0.3, bounce: 0 },
  popover: { duration: 0.18, ease: ease.out },
  modal: { duration: 0.24, ease: ease.out },
  exitFactor: 0.6,
} as const;

/** Once-per-visit motion on the landing page: hero letters, the reel and the afterimage. */
export const kinetic = {
  heroLetter: { duration: 0.6, ease: ease.out },
  /** Delay per letter, eased so the wave slows toward the end. */
  heroStep: 0.035,
  reelSwap: { type: "spring", duration: 0.5, bounce: 0.1 },
  /** Two afterimages: lag in seconds and opacity of each. */
  ghost: { lag: [0.04, 0.09], opacity: [0.14, 0.06] },
} as const;

/** Spring presets. */
export const spring = {
  snappy: { type: "spring", stiffness: 500, damping: 30 },
  smooth: { type: "spring", stiffness: 260, damping: 26 },
  bouncy: { type: "spring", stiffness: 300, damping: 15 },
} as const satisfies Record<string, Transition>;

/** Stagger between siblings, in seconds (0.03–0.06). */
export const stagger = {
  tight: 0.03,
  base: 0.045,
  loose: 0.06,
} as const;

/** Blur + fade + y-offset. Falls back to a plain fade under reduced motion. */
export function enterVariants(reduceMotion?: boolean | null, y = 8): Variants {
  if (reduceMotion) {
    return {
      hidden: { opacity: 0 },
      visible: { opacity: 1, transition: { duration: duration.base } },
      exit: { opacity: 0, transition: { duration: duration.quick } },
    };
  }
  return {
    hidden: { opacity: 0, y, filter: "blur(4px)" },
    visible: {
      opacity: 1,
      y: 0,
      filter: "blur(0px)",
      transition: { duration: duration.base, ease: ease.out },
    },
    exit: {
      opacity: 0,
      y: -y / 2,
      filter: "blur(4px)",
      transition: { duration: duration.quick, ease: ease.out },
    },
  };
}

/** Scale 0.96 → 1 for popovers, menus and dialogs. */
export function overlayVariants(reduceMotion?: boolean | null): Variants {
  if (reduceMotion) {
    return {
      hidden: { opacity: 0 },
      visible: { opacity: 1, transition: { duration: duration.quick } },
      exit: { opacity: 0, transition: { duration: duration.instant } },
    };
  }
  return {
    hidden: { opacity: 0, scale: 0.96, filter: "blur(2px)" },
    visible: {
      opacity: 1,
      scale: 1,
      filter: "blur(0px)",
      transition: { duration: duration.quick, ease: ease.out },
    },
    exit: {
      opacity: 0,
      scale: 0.96,
      filter: "blur(2px)",
      transition: { duration: duration.instant + 0.02, ease: ease.out },
    },
  };
}

/** Parent variants that stagger their children in. */
export function staggerVariants(gap: number = stagger.base, delayChildren = 0): Variants {
  return {
    hidden: {},
    visible: { transition: { staggerChildren: gap, delayChildren } },
    exit: { transition: { staggerChildren: gap / 2, staggerDirection: -1 } },
  };
}

Copy the source

components/ui/command-palette/command-palette.tsx

"use client";

import { useEffect, useId, useMemo, useRef, useState, type KeyboardEvent, type ReactNode } from "react";
import { AnimatePresence, LayoutGroup, motion, useReducedMotion } from "motion/react";
import { Dialog } from "radix-ui";
import { CornerDownLeft, Search } from "lucide-react";
import { cn } from "@/lib/utils";
import { duration, overlayVariants, spring } from "@/lib/motion";

export interface CommandPaletteItem {
  /** Unique id. */
  id: string;
  /** Visible label; the main thing search matches. */
  label: string;
  /** Group heading the item appears under. */
  group?: string;
  /** Secondary text, e.g. a path or hint. */
  description?: string;
  /** Icon before the label. */
  icon?: ReactNode;
  /** Keys shown at the end, e.g. ["⌘", "N"]. Display only. */
  shortcut?: string[];
  /** Extra words that should match, e.g. synonyms. */
  keywords?: string[];
  /** Prevents choosing the item. */
  disabled?: boolean;
  /** Runs when the item is chosen. */
  onSelect?: () => void;
}

export interface CommandPaletteProps {
  /** Commands, in display order. */
  items: CommandPaletteItem[];
  /** Controlled open state. */
  open?: boolean;
  /** Initial open state when uncontrolled. @default false */
  defaultOpen?: boolean;
  /** Called when the palette opens or closes. */
  onOpenChange?: (open: boolean) => void;
  /** Element that opens the palette, e.g. a search button. */
  trigger?: ReactNode;
  /** Letter that toggles the palette together with ⌘ (Mac) or Ctrl. false turns it off. @default "k" */
  hotkey?: string | false;
  /** Placeholder for the search field. @default "Type a command or search…" */
  placeholder?: string;
  /** Text shown when nothing matches. @default "No results found." */
  emptyText?: string;
  /** Close after an item is chosen. @default true */
  closeOnSelect?: boolean;
}

/** Characters of the query appear in order in the text; tighter runs score higher. */
function fuzzy(query: string, text: string) {
  let score = 0;
  let run = 0;
  let from = 0;
  for (const ch of query) {
    const at = text.indexOf(ch, from);
    if (at === -1) return 0;
    run = at === from ? run + 1 : 0;
    score += 1 + run;
    from = at + 1;
  }
  return (score / (query.length * 3)) * 20;
}

function rank(query: string, item: CommandPaletteItem) {
  const label = item.label.toLowerCase();
  if (label === query) return 100;
  if (label.startsWith(query)) return 80;
  if (label.split(/[\s/-]+/).some((w) => w.startsWith(query))) return 60;
  if (label.includes(query)) return 50;
  const loose = fuzzy(query.replace(/\s+/g, ""), label);
  if (loose > 0) return 20 + loose;
  const extra = [item.description, item.group, ...(item.keywords ?? [])].join(" ").toLowerCase();
  return extra.includes(query) ? 10 : 0;
}

export function CommandPalette({
  items,
  open,
  defaultOpen = false,
  onOpenChange,
  trigger,
  hotkey = "k",
  placeholder = "Type a command or search…",
  emptyText = "No results found.",
  closeOnSelect = true,
}: CommandPaletteProps) {
  const [internalOpen, setInternalOpen] = useState(defaultOpen);
  const isOpen = open ?? internalOpen;
  const [query, setQuery] = useState("");
  const [active, setActive] = useState(0);
  const listRef = useRef<HTMLDivElement>(null);
  const reduceMotion = useReducedMotion();
  const listId = useId();
  const groupId = useId();

  const setOpen = (next: boolean) => {
    if (!next) {
      setQuery("");
      setActive(0);
    }
    if (open === undefined) setInternalOpen(next);
    onOpenChange?.(next);
  };
  const setOpenRef = useRef(setOpen);
  useEffect(() => {
    setOpenRef.current = setOpen;
  });

  useEffect(() => {
    if (!hotkey) return;
    const onKeyDown = (event: globalThis.KeyboardEvent) => {
      if (event.key.toLowerCase() === hotkey.toLowerCase() && (event.metaKey || event.ctrlKey) && !event.altKey) {
        event.preventDefault();
        setOpenRef.current(!isOpen);
      }
    };
    window.addEventListener("keydown", onKeyDown);
    return () => window.removeEventListener("keydown", onKeyDown);
  }, [hotkey, isOpen]);

  const results = useMemo(() => {
    const q = query.trim().toLowerCase();
    if (!q) return items;
    return items
      .map((item) => ({ item, score: rank(q, item) }))
      .filter((r) => r.score > 0)
      .sort((a, b) => b.score - a.score)
      .map((r) => r.item);
  }, [items, query]);

  // Grouped while browsing; a single ranked list while searching.
  const sections = useMemo(() => {
    if (query.trim()) return [{ name: "Results", items: results }];
    const map = new Map<string, CommandPaletteItem[]>();
    for (const item of results) map.set(item.group ?? "", [...(map.get(item.group ?? "") ?? []), item]);
    return [...map].map(([name, sectionItems]) => ({ name, items: sectionItems }));
  }, [query, results]);

  useEffect(() => {
    listRef.current?.querySelector(`[data-index="${active}"]`)?.scrollIntoView({ block: "nearest" });
  }, [active]);

  function move(from: number, dir: 1 | -1) {
    const count = results.length;
    if (!count) return;
    let index = from;
    for (let i = 0; i < count; i++) {
      index = (index + dir + count) % count;
      if (!results[index].disabled) break;
    }
    setActive(index);
  }

  function choose(item: CommandPaletteItem | undefined) {
    if (!item || item.disabled) return;
    item.onSelect?.();
    if (closeOnSelect) setOpen(false);
  }

  function onInputKey(event: KeyboardEvent<HTMLInputElement>) {
    if (event.key === "ArrowDown") {
      event.preventDefault();
      move(active, 1);
    } else if (event.key === "ArrowUp") {
      event.preventDefault();
      move(active, -1);
    } else if (event.key === "Enter") {
      event.preventDefault();
      choose(results[active]);
    }
  }

  let index = -1;

  return (
    <Dialog.Root open={isOpen} onOpenChange={setOpen}>
      {trigger ? <Dialog.Trigger asChild>{trigger}</Dialog.Trigger> : null}
      <AnimatePresence>
        {isOpen ? (
          <Dialog.Portal forceMount>
            <Dialog.Overlay asChild forceMount>
              <motion.div
                className="fixed inset-0 z-50 bg-zinc-950/20 backdrop-blur-[2px]"
                initial={{ opacity: 0 }}
                animate={{ opacity: 1 }}
                exit={{ opacity: 0 }}
                transition={{ duration: duration.quick }}
              />
            </Dialog.Overlay>
            <div className="pointer-events-none fixed inset-0 z-50 flex items-start justify-center px-4 pt-[min(15vh,8rem)]">
              <Dialog.Content asChild forceMount aria-describedby={undefined}>
                <motion.div
                  variants={overlayVariants(reduceMotion)}
                  initial="hidden"
                  animate="visible"
                  exit="exit"
                  className="pointer-events-auto w-full max-w-[36rem] overflow-hidden rounded-[14px] border border-border bg-popover text-popover-foreground shadow-xl outline-none"
                >
                  <Dialog.Title className="sr-only">Command palette</Dialog.Title>
                  <div className="flex h-13 items-center gap-2.5 border-b border-border px-4">
                    <Search className="size-4 shrink-0 text-muted-foreground" aria-hidden="true" />
                    <input
                      autoFocus
                      value={query}
                      onChange={(event) => {
                        setQuery(event.target.value);
                        setActive(0);
                      }}
                      onKeyDown={onInputKey}
                      role="combobox"
                      aria-expanded="true"
                      aria-controls={listId}
                      aria-autocomplete="list"
                      aria-activedescendant={results.length ? `${listId}-${active}` : undefined}
                      aria-label="Search commands"
                      placeholder={placeholder}
                      spellCheck={false}
                      className="h-full min-w-0 flex-1 bg-transparent text-[15px] text-foreground outline-none placeholder:text-muted-foreground"
                    />
                    <kbd className="rounded-[5px] border border-border px-1.5 py-0.5 font-sans text-[11px] text-muted-foreground">Esc</kbd>
                  </div>

                  <LayoutGroup id={groupId}>
                    <div
                      ref={listRef}
                      id={listId}
                      role="listbox"
                      aria-label="Commands"
                      className="max-h-[min(55vh,24rem)] overflow-y-auto overscroll-contain p-1.5"
                    >
                      {results.length === 0 ? (
                        <p className="px-3 py-10 text-center text-sm text-muted-foreground">{emptyText}</p>
                      ) : (
                        sections.map((section) => (
                          <div key={section.name || "ungrouped"} role="group" aria-label={section.name || undefined} className="pb-1">
                            {section.name ? (
                              <p aria-hidden="true" className="px-2.5 pt-2 pb-1.5 text-xs font-medium text-muted-foreground">
                                {section.name}
                              </p>
                            ) : null}
                            {section.items.map((item) => {
                              index += 1;
                              const itemIndex = index;
                              const isActive = itemIndex === active;
                              return (
                                <div
                                  key={item.id}
                                  id={`${listId}-${itemIndex}`}
                                  role="option"
                                  aria-selected={isActive}
                                  aria-disabled={item.disabled || undefined}
                                  data-index={itemIndex}
                                  onPointerMove={() => !isActive && !item.disabled && setActive(itemIndex)}
                                  onClick={() => choose(item)}
                                  className={cn(
                                    "relative flex min-h-11 cursor-pointer items-center gap-3 rounded-[10px] px-2.5 py-2",
                                    item.disabled && "cursor-not-allowed opacity-45",
                                  )}
                                >
                                  {isActive && !item.disabled ? (
                                    <motion.span
                                      layoutId="active-row"
                                      aria-hidden="true"
                                      transition={reduceMotion ? { duration: 0 } : spring.snappy}
                                      className="absolute inset-0 rounded-[10px] bg-accent"
                                    />
                                  ) : null}
                                  {item.icon ? (
                                    <span className="relative flex size-7 shrink-0 items-center justify-center rounded-md border border-border bg-background text-muted-foreground [&_svg]:size-3.5">
                                      {item.icon}
                                    </span>
                                  ) : null}
                                  <span className="relative min-w-0 flex-1">
                                    <span className="block truncate text-sm text-foreground">{item.label}</span>
                                    {item.description ? (
                                      <span className="block truncate text-xs text-muted-foreground">{item.description}</span>
                                    ) : null}
                                  </span>
                                  {item.shortcut ? (
                                    <span className="relative flex shrink-0 gap-1" aria-hidden="true">
                                      {item.shortcut.map((key) => (
                                        <kbd
                                          key={key}
                                          className="inline-flex h-5 min-w-5 items-center justify-center rounded-[5px] border border-border bg-background px-1 font-sans text-[11px] text-muted-foreground"
                                        >
                                          {key}
                                        </kbd>
                                      ))}
                                    </span>
                                  ) : isActive ? (
                                    <CornerDownLeft className="relative size-3.5 shrink-0 text-muted-foreground" aria-hidden="true" />
                                  ) : null}
                                </div>
                              );
                            })}
                          </div>
                        ))
                      )}
                    </div>
                  </LayoutGroup>

                  <div className="hidden items-center gap-4 border-t border-border px-4 py-2.5 text-xs text-muted-foreground sm:flex">
                    <span>↑↓ to navigate</span>
                    <span>↵ to select</span>
                    <span className="ml-auto tabular-nums">
                      {results.length} {results.length === 1 ? "result" : "results"}
                    </span>
                  </div>
                </motion.div>
              </Dialog.Content>
            </div>
          </Dialog.Portal>
        ) : null}
      </AnimatePresence>
    </Dialog.Root>
  );
}

Usage

import { CommandPalette } from "@/components/ui/command-palette/command-palette";

export function AppCommands() {
  const router = useRouter();
  return (
    <CommandPalette
      items={[
        { id: "home", group: "Navigation", label: "Go home", onSelect: () => router.push("/") },
        { id: "new", group: "Actions", label: "New project", shortcut: ["⌘", "N"], onSelect: createProject },
      ]}
    />
  );
}

API reference

Prop	Type	Default	Description
`items*`	`CommandPaletteItem[]`	–	Commands, in display order.
`open`	`boolean`	–	Controlled open state.
`defaultOpen`	`boolean`	`false`	Initial open state when uncontrolled.
`onOpenChange`	`(open: boolean) => void`	–	Called when the palette opens or closes.
`trigger`	`ReactNode`	–	Element that opens the palette, e.g. a search button.
`hotkey`	`string \| false`	`"k"`	Letter that toggles the palette together with ⌘ (Mac) or Ctrl. false turns it off.
`placeholder`	`string`	`"Type a command or search…"`	Placeholder for the search field.
`emptyText`	`string`	`"No results found."`	Text shown when nothing matches.
`closeOnSelect`	`boolean`	`true`	Close after an item is chosen.

Ranking favours exact and prefix matches, then word starts, substrings and loose in-order matches, then description, group and keyword hits.
The hotkey toggles with ⌘ on Mac and Ctrl elsewhere. Pick a letter your app and the browser don't already use, or pass false.

Accessibility

Built on Radix Dialog: focus is trapped, Escape closes, scroll is locked and focus returns to whatever opened it.
The search field is a combobox that controls the listbox through aria-activedescendant, so screen readers announce the active command as you arrow through.
Groups are labelled; disabled commands are announced as unavailable and skipped by the arrow keys.
Shortcut hints are decorative (aria-hidden); the palette doesn't bind them, so wire real shortcuts separately.
With reduced motion enabled, the palette fades without scaling and the active row jumps instead of springing.

Installation#

CLI