Search Command

Search pages and run actions from a polished, keyboard-first command menu.

Example

Features

• Matches the compact search command used in the TentUI navigation bar.
• Opens with Mod+K or / and displays the correct Command or Control key for the user's platform.
• Groups pages, actions, and settings with icons, searchable descriptions, metadata, disabled states, and hotkey hints.
• Supports controlled and uncontrolled dialog state.
• Keeps routing framework-agnostic through item and global selection callbacks.
• Ignores slash shortcuts while the user is typing in an input, select, textarea, or editable region.
• Updates the footer action as keyboard or pointer selection moves between groups.

Installation

pnpm dlx shadcn@latest add @tentui/search-command

Usage

import { SearchCommand } from "@/components/search-command";

const groups = [
  {
    heading: "Menu",
    actionLabel: "Go to page",
    items: [
      {
        title: "Home",
        description: "Workspace overview",
        keywords: ["dashboard"],
        shortcut: "GH",
      },
      {
        title: "Settings",
        description: "Preferences and integrations",
        shortcut: "GS",
      },
    ],
  },
];
 
<SearchCommand
  groups={groups}
  onItemSelect={(item) => console.log(item.title)}
/>

Routing

Keep navigation in the application layer so the component works with Next.js, React Router, TanStack Router, or regular browser navigation.

const router = useRouter();
 
const groups = [
  {
    heading: "Pages",
    items: [
      { title: "Home", value: "/" },
      { title: "Customers", value: "/customers" },
    ],
  },
];
 
<SearchCommand
  groups={groups}
  onItemSelect={(item) => router.push(item.value ?? "/")}
/>

Actions

Add onSelect to an item when it owns an action. Both the item callback and onItemSelect run after the menu closes.

{
  title: "Create document",
  keywords: ["new", "page"],
  onSelect: createDocument,
}

Settings

Settings use the same item API as pages and actions. For example, add an appearance group with next-themes.

const { setTheme } = useTheme();
 
const themeGroup = {
  heading: "Theme",
  actionLabel: "Change theme",
  items: [
    {
      title: "Light",
      icon: <SunMediumIcon />,
      onSelect: () => setTheme("light"),
    },
    {
      title: "Dark",
      icon: <MoonStarIcon />,
      onSelect: () => setTheme("dark"),
    },
    {
      title: "System",
      icon: <MonitorIcon />,
      onSelect: () => setTheme("system"),
    },
  ],
};
 
<SearchCommand groups={[...groups, themeGroup]} />

Pass enabledHotkeys={false} if another command palette already owns Mod+K and / on the page. The shortcut keys remain visible in the trigger.

Accessibility

The trigger exposes its dialog state and Meta+K, Control+K, and / shortcuts. The dialog has a configurable title and description for assistive technology, all items live inside command groups, and slash is ignored while the user is editing text.

API reference