Command

A searchable command palette, with a nested stack for layered lists.

Default

CommandDialog centers a searchable list over an overlay. Group items with CommandGroup headings, split sections with CommandSeparator and show shortcuts with CommandShortcut.

import { useState } from "react";
import {
  AgentsIcon,
  ArrowRightIcon,
  Button,
  Command,
  CommandDialog,
  CommandEmpty,
  CommandFooter,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
  PlusIcon,
  SettingsIcon,
} from "@smallest-inc/ui";

export default function CommandDefault() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button variant="secondary" onClick={() => setOpen(true)}>
        Open command menu
      </Button>
      <CommandDialog open={open} onOpenChange={setOpen} title="Command menu" description="Search commands and pages.">
        <Command>
          <CommandInput placeholder="Search commands…" />
          <CommandList>
            <CommandEmpty>No results found.</CommandEmpty>
            <CommandGroup heading="Agents">
              <CommandItem onSelect={() => setOpen(false)}>
                <PlusIcon />
                Create agent
                <CommandShortcut>⌘N</CommandShortcut>
              </CommandItem>
              <CommandItem onSelect={() => setOpen(false)}>
                <AgentsIcon />
                View all agents
              </CommandItem>
            </CommandGroup>
            <CommandGroup heading="Go to">
              <CommandItem onSelect={() => setOpen(false)}>
                <ArrowRightIcon />
                Call logs
              </CommandItem>
              <CommandItem onSelect={() => setOpen(false)}>
                <ArrowRightIcon />
                Phone numbers
              </CommandItem>
              <CommandItem onSelect={() => setOpen(false)}>
                <ArrowRightIcon />
                Voice library
              </CommandItem>
            </CommandGroup>
            <CommandSeparator />
            <CommandGroup heading="Settings">
              <CommandItem onSelect={() => setOpen(false)}>
                <SettingsIcon />
                Workspace settings
                <CommandShortcut>⌘,</CommandShortcut>
              </CommandItem>
            </CommandGroup>
          </CommandList>
          <CommandFooter />
        </Command>
      </CommandDialog>
    </>
  );
}

Keyboard shortcut

Open the menu from a global shortcut and show the same keys on the trigger. This example uses ⌘J because the docs search owns ⌘K.

import { useEffect, useState } from "react";
import {
  ArrowRightIcon,
  Button,
  Command,
  CommandDialog,
  CommandEmpty,
  CommandFooter,
  CommandInput,
  CommandItem,
  CommandList,
} from "@smallest-inc/ui";

const pages = ["Agents", "Call logs", "Phone numbers", "Voice library", "Billing"];

export default function CommandKeyboardShortcut() {
  const [open, setOpen] = useState(false);

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

  return (
    <>
      <Button variant="secondary" keys="⌘J" onClick={() => setOpen(true)}>
        Search
      </Button>
      <CommandDialog open={open} onOpenChange={setOpen} title="Search" description="Jump to a page.">
        <Command>
          <CommandInput placeholder="Go to…" />
          <CommandList>
            <CommandEmpty>No pages found.</CommandEmpty>
            {pages.map((page) => (
              <CommandItem key={page} onSelect={() => setOpen(false)}>
                <ArrowRightIcon />
                {page}
              </CommandItem>
            ))}
          </CommandList>
          <CommandFooter />
        </Command>
      </CommandDialog>
    </>
  );
}

Entity items

Pass layout="entity" for 60px rows with a 40px avatar, a title and a description, such as agents or contacts.

import { useState } from "react";
import {
  Button,
  Command,
  CommandDialog,
  CommandEmpty,
  CommandFooter,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  Entity,
  EntityContent,
  EntityMedia,
} from "@smallest-inc/ui";

const agents = [
  { name: "Support agent", description: "Inbound · English, Spanish" },
  { name: "Renewals agent", description: "Outbound · 1,240 contacts" },
  { name: "Appointment reminders", description: "Outbound · Scheduled daily at 9:00" },
  { name: "Front desk", description: "Inbound · After hours only" },
];

export default function CommandEntity() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button variant="secondary" onClick={() => setOpen(true)}>
        Switch agent
      </Button>
      <CommandDialog open={open} onOpenChange={setOpen} title="Switch agent" description="Search agents by name.">
        <Command>
          <CommandInput placeholder="Search agents…" />
          <CommandList>
            <CommandEmpty>No agents found.</CommandEmpty>
            <CommandGroup heading="Agents">
              {agents.map((agent) => (
                <CommandItem key={agent.name} layout="entity" onSelect={() => setOpen(false)}>
                  <Entity>
                    <EntityMedia />
                    <EntityContent title={agent.name} description={agent.description} />
                  </Entity>
                </CommandItem>
              ))}
            </CommandGroup>
          </CommandList>
          <CommandFooter />
        </Command>
      </CommandDialog>
    </>
  );
}

Close button

Pass showCloseButton when the menu is a picker rather than a quick launcher. Escape and a click outside still close it.

import { useState } from "react";
import {
  ArrowRightIcon,
  Button,
  Command,
  CommandDialog,
  CommandEmpty,
  CommandFooter,
  CommandInput,
  CommandItem,
  CommandList,
} from "@smallest-inc/ui";

const numbers = ["+1 415 555 0132", "+1 646 555 0187", "+44 20 7946 0958"];

export default function CommandCloseButton() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button variant="secondary" onClick={() => setOpen(true)}>
        Assign number
      </Button>
      <CommandDialog
        open={open}
        onOpenChange={setOpen}
        showCloseButton
        title="Assign number"
        description="Choose a phone number for Support agent."
      >
        <Command>
          <CommandInput placeholder="Search numbers…" className="pr-8" />
          <CommandList>
            <CommandEmpty>No numbers found.</CommandEmpty>
            {numbers.map((number) => (
              <CommandItem key={number} onSelect={() => setOpen(false)}>
                <ArrowRightIcon />
                {number}
              </CommandItem>
            ))}
          </CommandList>
          <CommandFooter />
        </Command>
      </CommandDialog>
    </>
  );
}

Footer

CommandFooter shows the navigate and select key hints by default. Pass children to replace them with a count or a link out.

import { useState } from "react";
import {
  ArrowRightIcon,
  Button,
  Command,
  CommandDialog,
  CommandEmpty,
  CommandFooter,
  CommandInput,
  CommandItem,
  CommandList,
} from "@smallest-inc/ui";

const voices = ["Emily · Warm", "Arjun · Clear", "Sofia · Bright", "Marcus · Calm"];

export default function CommandFooterExample() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button variant="secondary" onClick={() => setOpen(true)}>
        Choose voice
      </Button>
      <CommandDialog open={open} onOpenChange={setOpen} title="Choose voice" description="Search the voice library.">
        <Command>
          <CommandInput placeholder="Search voices…" />
          <CommandList>
            <CommandEmpty>No voices found.</CommandEmpty>
            {voices.map((voice) => (
              <CommandItem key={voice} onSelect={() => setOpen(false)}>
                <ArrowRightIcon />
                {voice}
              </CommandItem>
            ))}
          </CommandList>
          <CommandFooter>
            <span className="text-fg-tertiary">48 voices</span>
            <Button variant="link" size="sm" onClick={() => setOpen(false)}>
              Open voice library
            </Button>
          </CommandFooter>
        </Command>
      </CommandDialog>
    </>
  );
}

Nested

Render a CommandDialog inside another and open it from an item's nestedSelect. The front card presses in on pointer down, then settles into a stack behind the new layer. Escape goes back one layer.

import { useState } from "react";
import {
  AgentsIcon,
  ArrowRightIcon,
  Button,
  Command,
  CommandDialog,
  CommandEmpty,
  CommandFooter,
  CommandInput,
  CommandItem,
  CommandList,
  SettingsIcon,
} from "@smallest-inc/ui";

const members = ["Ada Lovelace", "Alan Turing", "Grace Hopper", "Katherine Johnson"];

export default function CommandNested() {
  const [open, setOpen] = useState(false);
  const [teamOpen, setTeamOpen] = useState(false);
  const [membersOpen, setMembersOpen] = useState(false);

  const closeAll = () => {
    setOpen(false);
    setTeamOpen(false);
    setMembersOpen(false);
  };

  return (
    <>
      <Button variant="secondary" onClick={() => setOpen(true)}>
        Open workspace menu
      </Button>
      <CommandDialog
        open={open}
        onOpenChange={(nextOpen) => (nextOpen ? setOpen(true) : closeAll())}
        title="Workspace"
        description="Search the workspace."
      >
        <Command>
          <CommandInput placeholder="Search workspace…" />
          <CommandList>
            <CommandEmpty>No results found.</CommandEmpty>
            <CommandItem nestedSelect={() => setTeamOpen(true)}>
              <AgentsIcon />
              Team
            </CommandItem>
            <CommandItem onSelect={closeAll}>
              <SettingsIcon />
              Workspace settings
            </CommandItem>
          </CommandList>
          <CommandFooter />
        </Command>

        <CommandDialog
          open={teamOpen}
          onOpenChange={(nextOpen) => {
            setTeamOpen(nextOpen);
            if (!nextOpen) setMembersOpen(false);
          }}
          title="Team"
          description="Search the team."
        >
          <Command>
            <CommandInput placeholder="Search in Team…" />
            <CommandList>
              <CommandEmpty>No results found.</CommandEmpty>
              <CommandItem nestedSelect={() => setMembersOpen(true)}>
                <ArrowRightIcon />
                Members
              </CommandItem>
              <CommandItem onSelect={closeAll}>
                <ArrowRightIcon />
                Pending invitations
              </CommandItem>
            </CommandList>
            <CommandFooter />
          </Command>

          <CommandDialog
            open={membersOpen}
            onOpenChange={setMembersOpen}
            title="Members"
            description="Search people on this team."
          >
            <Command>
              <CommandInput placeholder="Search members…" />
              <CommandList>
                <CommandEmpty>No members found.</CommandEmpty>
                {members.map((name) => (
                  <CommandItem key={name} onSelect={closeAll}>
                    {name}
                  </CommandItem>
                ))}
              </CommandList>
              <CommandFooter />
            </Command>
          </CommandDialog>
        </CommandDialog>
      </CommandDialog>
    </>
  );
}

Best practices

When to use

Use for a keyboard-first launcher or picker across many destinations and actions: go to a page, switch agent, assign a number.
Use Combobox or Select for choosing a value inside a form, and Dropdown Menu for a few actions on one object.

Behavior

Open CommandDialog with open/onOpenChange from a trigger and a global shortcut, and show the same keys on the trigger (Button keys).
Close the dialog in each item's onSelect. Use nestedSelect to push a nested CommandDialog; Escape goes back one layer.
Pass showCloseButton when the menu is a picker rather than a quick launcher.

Content

Pass a sentence-case title and description to CommandDialog; they are visually hidden but announced.
Group items under short CommandGroup headings, lead compact items with a 20px icon, and use layout="entity" for people or agents with a second line.
Always include CommandEmpty with a specific message (“No agents found.”) and keep the placeholder action-oriented (“Search agents…”).

Accessibility

Keep CommandFooter's navigate and select hints, or replace them with equally clear text; every item must be reachable with the arrow keys.

PreviousCombobox NextDialog