Command

A command palette in the style of Spotlight, built on cmdk.

@cupertinoui/commandRegistry JSON

"use client"

import { AppWindowIcon, CalculatorIcon, CalendarIcon, FileTextIcon, SettingsIcon } from "lucide-react"

import {
  Command,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
} from "@/components/ui/command"

// Spotlight: type to search apps, documents and actions.
export default function CommandDemo() {
  return (
    <Command className="w-full max-w-md">
      <CommandInput placeholder="Spotlight Search" />
      <CommandList>
        <CommandEmpty>No results.</CommandEmpty>
        <CommandGroup heading="Applications">
          <CommandItem>
            <CalendarIcon /> Calendar
          </CommandItem>
          <CommandItem>
            <CalculatorIcon /> Calculator
          </CommandItem>
          <CommandItem>
            <SettingsIcon /> System Settings
            <CommandShortcut>⌘,</CommandShortcut>
          </CommandItem>
        </CommandGroup>
        <CommandSeparator />
        <CommandGroup heading="Documents">
          <CommandItem>
            <FileTextIcon /> Roadmap.key
          </CommandItem>
          <CommandItem>
            <AppWindowIcon /> Show All Windows
            <CommandShortcut>⌃↑</CommandShortcut>
          </CommandItem>
        </CommandGroup>
      </CommandList>
    </Command>
  )
}

Installation

pnpm dlx shadcn@latest add @cupertinoui/command

The first install also adds the macOS theme. See Installation to set up the registry.

Usage

import { Command, CommandGroup, CommandInput, CommandItem, CommandList } from "@/components/ui/command"

<Command>
  <CommandInput placeholder="Spotlight Search" />
  <CommandList>
    <CommandGroup heading="Applications">
      <CommandItem>Calendar</CommandItem>
    </CommandGroup>
  </CommandList>
</Command>

Examples

Dialog

⌘K opens the palette over the page, like Spotlight.

"use client"

import * as React from "react"
import { CalculatorIcon, CalendarIcon, MusicIcon, SettingsIcon } from "lucide-react"

import { Button } from "@/components/ui/button"
import {
  Command,
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
} from "@/components/ui/command"
import { Kbd } from "@/components/ui/kbd"

// ⌘K (or the button) opens the palette over the page, like Spotlight.
export default function CommandDialogDemo() {
  const [open, setOpen] = React.useState(false)

  React.useEffect(() => {
    const down = (event: KeyboardEvent) => {
      if (event.key === "k" && (event.metaKey || event.ctrlKey)) {
        event.preventDefault()
        setOpen((value) => !value)
      }
    }
    document.addEventListener("keydown", down)
    return () => document.removeEventListener("keydown", down)
  }, [])

  return (
    <>
      <Button variant="secondary" onClick={() => setOpen(true)}>
        Open Spotlight <Kbd>⌘K</Kbd>
      </Button>
      <CommandDialog open={open} onOpenChange={setOpen}>
        <Command>
          <CommandInput placeholder="Spotlight Search" />
          <CommandList>
            <CommandEmpty>No results.</CommandEmpty>
            <CommandGroup heading="Applications">
              {[
                { label: "Calendar", icon: CalendarIcon },
                { label: "Calculator", icon: CalculatorIcon },
                { label: "Music", icon: MusicIcon },
                { label: "System Settings", icon: SettingsIcon },
              ].map((item) => (
                <CommandItem key={item.label} onSelect={() => setOpen(false)}>
                  <item.icon /> {item.label}
                </CommandItem>
              ))}
            </CommandGroup>
          </CommandList>
        </Command>
      </CommandDialog>
    </>
  )
}

API Reference

Every part forwards the props of the underlying element. The props below are the ones CupertinoUI adds or changes.

CommandDialog

Prop	Type	Description
`open / onOpenChange`		Shows the palette in a dialog.
`title / description`	`string`	For screen readers.
`className`	`string`	Extra classes, merged with the component's own.

Command / CommandInput / CommandList / CommandGroup / CommandItem / CommandShortcut / CommandEmpty / CommandSeparator

Prop	Type	Description
`className`	`string`	Extra classes, merged with the component's own.