Command

A searchable list of actions, on the page or in a dialog.

Suggestions
New Document
Search Files
Toggle Theme
Settings
Members⌘M
Notifications⇧⌘N
Preferences⌘,
import { Fragment } from "react"
import * as stylex from "@stylexjs/stylex"
import {
  Command,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
} from "@/components/ui/command"
import { radius, width } from "@/theme/tokens.stylex"
import { BellIcon } from "@phosphor-icons/react/dist/csr/Bell"
import { FilePlusIcon } from "@phosphor-icons/react/dist/csr/FilePlus"
import { GearIcon } from "@phosphor-icons/react/dist/csr/Gear"
import { MagnifyingGlassIcon } from "@phosphor-icons/react/dist/csr/MagnifyingGlass"
import { MoonIcon } from "@phosphor-icons/react/dist/csr/Moon"
import { UsersIcon } from "@phosphor-icons/react/dist/csr/Users"
import type { Icon as PhosphorIcon } from "@phosphor-icons/react"

type Action = {
  value: string
  label: string
  icon: PhosphorIcon
  shortcut?: string
  disabled?: boolean
}
type Group = { value: string; items: Action[] }

const groups: Group[] = [
  {
    value: "Suggestions",
    items: [
      { value: "new-document", label: "New Document", icon: FilePlusIcon },
      { value: "search-files", label: "Search Files", icon: MagnifyingGlassIcon },
      { value: "toggle-theme", label: "Toggle Theme", icon: MoonIcon, disabled: true },
    ],
  },
  {
    value: "Settings",
    items: [
      { value: "members", label: "Members", icon: UsersIcon, shortcut: "⌘M" },
      { value: "notifications", label: "Notifications", icon: BellIcon, shortcut: "⇧⌘N" },
      { value: "preferences", label: "Preferences", icon: GearIcon, shortcut: "⌘," },
    ],
  },
]

const styles = stylex.create({
  command: { maxWidth: width.sm, borderRadius: radius.lg, borderWidth: 1, borderStyle: "solid" },
})

export default function CommandDemo() {
  return (
    <Command items={groups} xstyle={styles.command}>
      <CommandInput placeholder="Type a command or search..." aria-label="Search commands" />
      <CommandEmpty>No results found.</CommandEmpty>
      <CommandList>
        {(group: Group, index: number) => (
          <Fragment key={group.value}>
            {index > 0 && <CommandSeparator />}
            <CommandGroup heading={group.value} items={group.items}>
              {(item: Action) => (
                <CommandItem key={item.value} value={item} disabled={item.disabled}>
                  <item.icon />
                  <span>{item.label}</span>
                  {item.shortcut && <CommandShortcut>{item.shortcut}</CommandShortcut>}
                </CommandItem>
              )}
            </CommandGroup>
          </Fragment>
        )}
      </CommandList>
    </Command>
  )
}

About

Command is Base UI's Autocomplete rendered inline, not the cmdk package that shadcn's Command is built on. The list is always open, the input filters it, and an item runs its onClick when clicked or when Enter is pressed while it is highlighted. The trade-off is the data shape. Options go through items and render from a function child, the way a Combobox does.

Installation

pnpm dlx shadcn@latest add @arene/command

Needs the arene setup first. Also adds Button, Dialog, Input and Input Group.

Usage

import {
  Command,
  CommandDialog,
  CommandEmpty,
  CommandFooter,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
} from "@/components/ui/command"
const actions = [
  { value: "new-document", label: "New Document" },
  { value: "search-files", label: "Search Files" },
  { value: "toggle-theme", label: "Toggle Theme" },
]

export function Example() {
  return (
    <Command items={actions}>
      <CommandInput placeholder="Type a command or search..." aria-label="Search commands" />
      <CommandEmpty>No results found.</CommandEmpty>
      <CommandList>
        <CommandGroup heading="Suggestions" items={actions}>
          {(item: (typeof actions)[number]) => (
            <CommandItem key={item.value} value={item} onClick={() => run(item)}>
              {item.label}
            </CommandItem>
          )}
        </CommandGroup>
      </CommandList>
    </Command>
  )
}

Items shaped { value, label } filter on label. For any other shape, pass itemToStringValue to Command.

Composition

Command
├── CommandInput
├── CommandEmpty
└── CommandList
    ├── CommandGroup
    │   └── CommandItem
    ├── CommandSeparator
    └── CommandGroup
        └── CommandItem
└── CommandFooter

CommandEmpty sits before CommandList, not inside it. The list is a listbox, and a status message is not one of its options.

Command is a tray, and CommandList is the raised panel inside it. The input and CommandFooter sit on the tray. When nothing matches, the list drops its panel and the empty message shows on the tray.

Groups

Pass groups shaped { value, items } to items. CommandList takes a function child that receives each group; render a CommandGroup with the group's items and a function child that receives each item.

"use client"

import { Fragment, useState } from "react"
import { Button } from "@/components/ui/button"
import {
  Command,
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
} from "@/components/ui/command"
import { BellIcon } from "@phosphor-icons/react/dist/csr/Bell"
import { FilePlusIcon } from "@phosphor-icons/react/dist/csr/FilePlus"
import { GearIcon } from "@phosphor-icons/react/dist/csr/Gear"
import { MagnifyingGlassIcon } from "@phosphor-icons/react/dist/csr/MagnifyingGlass"
import { MoonIcon } from "@phosphor-icons/react/dist/csr/Moon"
import { UsersIcon } from "@phosphor-icons/react/dist/csr/Users"
import type { Icon as PhosphorIcon } from "@phosphor-icons/react"

type Action = { value: string; label: string; icon: PhosphorIcon; shortcut?: string }
type Group = { value: string; items: Action[] }

const groups: Group[] = [
  {
    value: "Suggestions",
    items: [
      { value: "new-document", label: "New Document", icon: FilePlusIcon },
      { value: "search-files", label: "Search Files", icon: MagnifyingGlassIcon },
      { value: "toggle-theme", label: "Toggle Theme", icon: MoonIcon },
    ],
  },
  {
    value: "Settings",
    items: [
      { value: "members", label: "Members", icon: UsersIcon, shortcut: "⌘M" },
      { value: "notifications", label: "Notifications", icon: BellIcon, shortcut: "⇧⌘N" },
      { value: "preferences", label: "Preferences", icon: GearIcon, shortcut: "⌘," },
    ],
  },
]

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

  return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)}>
        Open palette
      </Button>
      <CommandDialog open={open} onOpenChange={setOpen}>
        <Command items={groups}>
          <CommandInput placeholder="Type a command or search..." aria-label="Search commands" />
          <CommandEmpty>No results found.</CommandEmpty>
          <CommandList>
            {(group: Group, index: number) => (
              <Fragment key={group.value}>
                {index > 0 && <CommandSeparator />}
                <CommandGroup heading={group.value} items={group.items}>
                  {(item: Action) => (
                    <CommandItem key={item.value} value={item} onClick={() => setOpen(false)}>
                      <item.icon />
                      <span>{item.label}</span>
                      {item.shortcut && <CommandShortcut>{item.shortcut}</CommandShortcut>}
                    </CommandItem>
                  )}
                </CommandGroup>
              </Fragment>
            )}
          </CommandList>
        </Command>
      </CommandDialog>
    </>
  )
}

Filtering drops a group with no match left, so put the CommandSeparator before every group but the first rather than between groups.

Basic

Put the Command inside a CommandDialog and control it with open and onOpenChange. Close it from an item's onClick.

"use client"

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

type Action = { value: string; label: string }

const suggestions: Action[] = [
  { value: "new-document", label: "New Document" },
  { value: "search-files", label: "Search Files" },
  { value: "toggle-theme", label: "Toggle Theme" },
]

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

  return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)}>
        Open palette
      </Button>
      <CommandDialog open={open} onOpenChange={setOpen}>
        <Command items={suggestions}>
          <CommandInput placeholder="Type a command or search..." aria-label="Search commands" />
          <CommandEmpty>No results found.</CommandEmpty>
          <CommandList>
            <CommandGroup heading="Suggestions" items={suggestions}>
              {(item: Action) => (
                <CommandItem key={item.value} value={item} onClick={() => setOpen(false)}>
                  {item.label}
                </CommandItem>
              )}
            </CommandGroup>
          </CommandList>
        </Command>
      </CommandDialog>
    </>
  )
}

Dialog

Toggle the dialog from a keyboard shortcut. Nothing in the component binds one.

Press ⌘J

"use client"

import { Fragment, useEffect, useState } from "react"
import {
  Command,
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
} from "@/components/ui/command"
import { Kbd, KbdGroup } from "@/components/ui/kbd"
import { BellIcon } from "@phosphor-icons/react/dist/csr/Bell"
import { FilePlusIcon } from "@phosphor-icons/react/dist/csr/FilePlus"
import { GearIcon } from "@phosphor-icons/react/dist/csr/Gear"
import { MagnifyingGlassIcon } from "@phosphor-icons/react/dist/csr/MagnifyingGlass"
import { MoonIcon } from "@phosphor-icons/react/dist/csr/Moon"
import { UsersIcon } from "@phosphor-icons/react/dist/csr/Users"
import type { Icon as PhosphorIcon } from "@phosphor-icons/react"
import { Text } from "@/components/ui/text"

type Action = { value: string; label: string; icon: PhosphorIcon; shortcut?: string }
type Group = { value: string; items: Action[] }

const groups: Group[] = [
  {
    value: "Suggestions",
    items: [
      { value: "new-document", label: "New Document", icon: FilePlusIcon },
      { value: "search-files", label: "Search Files", icon: MagnifyingGlassIcon },
      { value: "toggle-theme", label: "Toggle Theme", icon: MoonIcon },
    ],
  },
  {
    value: "Settings",
    items: [
      { value: "members", label: "Members", icon: UsersIcon, shortcut: "⌘M" },
      { value: "notifications", label: "Notifications", icon: BellIcon, shortcut: "⇧⌘N" },
      { value: "preferences", label: "Preferences", icon: GearIcon, shortcut: "⌘," },
    ],
  },
]

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

  useEffect(() => {
    const down = (event: KeyboardEvent) => {
      if (event.key === "j" && (event.metaKey || event.ctrlKey)) {
        event.preventDefault()
        setOpen((open) => !open)
      }
    }

    document.addEventListener("keydown", down)
    return () => document.removeEventListener("keydown", down)
  }, [])

  return (
    <>
      <Text render={<p />} size="sm" tone="muted">
        Press{" "}
        <KbdGroup>
          <Kbd>⌘</Kbd>
          <Kbd>J</Kbd>
        </KbdGroup>
      </Text>
      <CommandDialog open={open} onOpenChange={setOpen}>
        <Command items={groups}>
          <CommandInput placeholder="Type a command or search..." aria-label="Search commands" />
          <CommandEmpty>No results found.</CommandEmpty>
          <CommandList>
            {(group: Group, index: number) => (
              <Fragment key={group.value}>
                {index > 0 && <CommandSeparator />}
                <CommandGroup heading={group.value} items={group.items}>
                  {(item: Action) => (
                    <CommandItem key={item.value} value={item} onClick={() => setOpen(false)}>
                      <item.icon />
                      <span>{item.label}</span>
                      {item.shortcut && <CommandShortcut>{item.shortcut}</CommandShortcut>}
                    </CommandItem>
                  )}
                </CommandGroup>
              </Fragment>
            )}
          </CommandList>
        </Command>
      </CommandDialog>
    </>
  )
}

Shortcuts

Use CommandShortcut to show a key combination at the trailing edge of an item. It displays the key only.

"use client"

import { useState } from "react"
import { Button } from "@/components/ui/button"
import {
  Command,
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandShortcut,
} from "@/components/ui/command"
import { BellIcon } from "@phosphor-icons/react/dist/csr/Bell"
import { GearIcon } from "@phosphor-icons/react/dist/csr/Gear"
import { UsersIcon } from "@phosphor-icons/react/dist/csr/Users"
import type { Icon as PhosphorIcon } from "@phosphor-icons/react"

type Action = { value: string; label: string; icon: PhosphorIcon; shortcut: string }

const settings: Action[] = [
  { value: "members", label: "Members", icon: UsersIcon, shortcut: "⌘M" },
  { value: "notifications", label: "Notifications", icon: BellIcon, shortcut: "⇧⌘N" },
  { value: "preferences", label: "Preferences", icon: GearIcon, shortcut: "⌘," },
]

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

  return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)}>
        Open palette
      </Button>
      <CommandDialog open={open} onOpenChange={setOpen}>
        <Command items={settings}>
          <CommandInput placeholder="Type a command or search..." aria-label="Search commands" />
          <CommandEmpty>No results found.</CommandEmpty>
          <CommandList>
            <CommandGroup heading="Settings" items={settings}>
              {(item: Action) => (
                <CommandItem key={item.value} value={item} onClick={() => setOpen(false)}>
                  <item.icon />
                  <span>{item.label}</span>
                  <CommandShortcut>{item.shortcut}</CommandShortcut>
                </CommandItem>
              )}
            </CommandGroup>
          </CommandList>
        </Command>
      </CommandDialog>
    </>
  )
}

Scrollable

The list stops at 18rem and scrolls. The highlighted item scrolls into view.

"use client"

import { Fragment, useState } from "react"
import { Button } from "@/components/ui/button"
import {
  Command,
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
} from "@/components/ui/command"
import { ArchiveIcon } from "@phosphor-icons/react/dist/csr/Archive"
import { BellIcon } from "@phosphor-icons/react/dist/csr/Bell"
import { CalendarBlankIcon } from "@phosphor-icons/react/dist/csr/CalendarBlank"
import { ChartBarIcon } from "@phosphor-icons/react/dist/csr/ChartBar"
import { ClockIcon } from "@phosphor-icons/react/dist/csr/Clock"
import { CodeIcon } from "@phosphor-icons/react/dist/csr/Code"
import { CopyIcon } from "@phosphor-icons/react/dist/csr/Copy"
import { FilePlusIcon } from "@phosphor-icons/react/dist/csr/FilePlus"
import { FolderPlusIcon } from "@phosphor-icons/react/dist/csr/FolderPlus"
import { GearIcon } from "@phosphor-icons/react/dist/csr/Gear"
import { ImageIcon } from "@phosphor-icons/react/dist/csr/Image"
import { MathOperationsIcon } from "@phosphor-icons/react/dist/csr/MathOperations"
import { MinusIcon } from "@phosphor-icons/react/dist/csr/Minus"
import { QuestionIcon } from "@phosphor-icons/react/dist/csr/Question"
import { StarIcon } from "@phosphor-icons/react/dist/csr/Star"
import { TableIcon } from "@phosphor-icons/react/dist/csr/Table"
import { TextBIcon } from "@phosphor-icons/react/dist/csr/TextB"
import { TextHIcon } from "@phosphor-icons/react/dist/csr/TextH"
import { TextItalicIcon } from "@phosphor-icons/react/dist/csr/TextItalic"
import { TrashIcon } from "@phosphor-icons/react/dist/csr/Trash"
import { UploadSimpleIcon } from "@phosphor-icons/react/dist/csr/UploadSimple"
import { UsersIcon } from "@phosphor-icons/react/dist/csr/Users"
import { UsersThreeIcon } from "@phosphor-icons/react/dist/csr/UsersThree"
import type { Icon as PhosphorIcon } from "@phosphor-icons/react"

type Action = { value: string; label: string; icon: PhosphorIcon; shortcut?: string }
type Group = { value: string; items: Action[] }

const groups: Group[] = [
  {
    value: "Go to",
    items: [
      { value: "recent", label: "Recent", icon: ClockIcon, shortcut: "⌘1" },
      { value: "starred", label: "Starred", icon: StarIcon, shortcut: "⌘2" },
      { value: "shared", label: "Shared with Me", icon: UsersIcon, shortcut: "⌘3" },
      { value: "archive", label: "Archive", icon: ArchiveIcon, shortcut: "⌘4" },
    ],
  },
  {
    value: "Create",
    items: [
      { value: "new-document", label: "New Document", icon: FilePlusIcon, shortcut: "⌘N" },
      { value: "new-folder", label: "New Folder", icon: FolderPlusIcon, shortcut: "⇧⌘N" },
      { value: "new-table", label: "New Table", icon: TableIcon },
      { value: "upload", label: "Upload File", icon: UploadSimpleIcon, shortcut: "⌘U" },
      { value: "duplicate", label: "Duplicate", icon: CopyIcon, shortcut: "⌘D" },
      { value: "delete", label: "Delete", icon: TrashIcon, shortcut: "⌫" },
    ],
  },
  {
    value: "Format",
    items: [
      { value: "bold", label: "Bold", icon: TextBIcon, shortcut: "⌘B" },
      { value: "italic", label: "Italic", icon: TextItalicIcon, shortcut: "⌘I" },
      { value: "heading", label: "Heading", icon: TextHIcon, shortcut: "⌥⌘1" },
      { value: "code-block", label: "Code Block", icon: CodeIcon, shortcut: "⌥⌘C" },
    ],
  },
  {
    value: "Workspace",
    items: [
      { value: "members", label: "Members", icon: UsersThreeIcon },
      { value: "notifications", label: "Notifications", icon: BellIcon },
      { value: "preferences", label: "Preferences", icon: GearIcon, shortcut: "⌘," },
      { value: "usage", label: "Usage", icon: ChartBarIcon },
      { value: "help", label: "Help", icon: QuestionIcon },
    ],
  },
  {
    value: "Insert",
    items: [
      { value: "image", label: "Image", icon: ImageIcon },
      { value: "date", label: "Date", icon: CalendarBlankIcon },
      { value: "equation", label: "Equation", icon: MathOperationsIcon },
      { value: "divider", label: "Divider", icon: MinusIcon },
    ],
  },
]

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

  return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)}>
        Open palette
      </Button>
      <CommandDialog open={open} onOpenChange={setOpen}>
        <Command items={groups}>
          <CommandInput placeholder="Type a command or search..." aria-label="Search commands" />
          <CommandEmpty>No results found.</CommandEmpty>
          <CommandList>
            {(group: Group, index: number) => (
              <Fragment key={group.value}>
                {index > 0 && <CommandSeparator />}
                <CommandGroup heading={group.value} items={group.items}>
                  {(item: Action) => (
                    <CommandItem key={item.value} value={item} onClick={() => setOpen(false)}>
                      <item.icon />
                      <span>{item.label}</span>
                      {item.shortcut && <CommandShortcut>{item.shortcut}</CommandShortcut>}
                    </CommandItem>
                  )}
                </CommandGroup>
              </Fragment>
            )}
          </CommandList>
        </Command>
      </CommandDialog>
    </>
  )
}

API reference

Pass render to replace a part's element or compose it with another component.

Every part wraps the Base UI Autocomplete part of the same name and accepts its props. See the Base UI reference for the full list. Each styled part also takes xstyle and className. CommandItem also takes style, which is real inline CSS merged over the style its Base UI state resolves to.

Command

PropTypeDefault
itemsreadonly Item[] | readonly Group[]—
autoHighlightboolean | "always""always"
keepHighlightbooleantrue
itemToStringValue(item: Item) => string—
filter(item, query, toString) => boolean—
valuestring—
onValueChange(value: string, details) => void—

value is the input's text. inline and open are set and cannot be changed.

CommandDialog

PropTypeDefault
openboolean—
onOpenChange(open: boolean, details) => void—
titlestring"Command Palette"
descriptionstring"Search for a command to run..."
showCloseButtonbooleanfalse

title and description are read to screen readers and not shown. From md up, the popup sits a third of the way down the viewport and stays put as the list changes height. Below md it fills the screen and the list takes the height above the on-screen keyboard. A full-screen panel has no outside to tap, so give it a way out, such as a Cancel button in CommandInput.

CommandInput

PropTypeDefault
childrenReactNode—

children render inside the field after the search icon. Pass an InputGroupAddon with align="inline-end" to put a button at the field's end:

<CommandInput placeholder="Search…">
  <InputGroupAddon align="inline-end">
    <DialogClose render={<InputGroupButton size="sm" />}>Cancel</DialogClose>
  </InputGroupAddon>
</CommandInput>

CommandGroup

PropTypeDefault
headingReactNode—
itemsreadonly Item[]—
childrenReactNode | (item: Item, index: number) => ReactNode—

CommandItem

PropTypeDefault
valueItem—
onClick(event) => void—
disabledbooleanfalse

commandStyles

The style maps behind the component. Spread them onto any element.

KeyWhat it is
rootThe tray: surface, radius, padding
listThe raised, scrolling results panel
emptyThe empty message
groupA group's padding
headingA group heading
separatorThe hairline between groups
itemAn item's row and type
itemHighlightedThe highlight fill and inset ring
itemDisabledThe dimmed, inert item
shortcutCommandShortcut
footerCommandFooter, a row on the tray

itemDisabled is disabled from states in theme/states.ts, the same dim every other control uses. root keeps its own fill. The tray is inline, so it takes no popup ring or shadow.

Data attributes

AttributeOnEffect
data-slot="command"the panelTargets the panel from a parent
data-slot="input-group"the fieldThe frame CommandInput renders
data-slot="command-list"the listTargets the list from a parent
data-slot="command-group"a groupTargets a group from a parent
data-slot="command-group-heading"a headingTargets a heading from a parent
data-slot="command-item"an itemTargets items from a parent
data-slot="command-footer"the footerTargets the footer from a parent
data-highlighted, data-disabledan itemBase UI writes them
data-slot="dialog-content"the dialogTargets the animated dialog panel