# Command
> Search and run actions from an inline list or command palette.
Source: https://www.honestui.com/docs/components/command
```tsx
"use client"
import * as React from "react"
import {
File as FileIcon,
Palette as PaletteIcon,
Search as SearchIcon,
Settings as SettingsIcon,
User as UserIcon,
} from "honestui/icons"
import {
Command,
CommandContent,
CommandEmpty,
CommandGroup,
CommandInput,
CommandItem,
CommandLabel,
CommandSeparator,
} from "@/components/honest-ui/ui/command"
export function CommandDemo() {
const [lastAction, setLastAction] = React.useState("No command selected")
return (
}
placeholder="Search commands..."
/>
No matching commands.
Navigation
}
trailingIcon={G then D}
onClick={() => setLastAction("Opened documents")}
>
Open documents
}
onClick={() => setLastAction("Opened account")}
>
Open account
Preferences
}
onClick={() => setLastAction("Opened appearance")}
>
Change appearance
}
onClick={() => setLastAction("Opened settings")}
>
Open settings
{lastAction}
)
}
```
## Overview [#overview]
Use Command to help people find and run actions from a compact, keyboard-oriented list. It works inline as a persistent command browser or inside `CommandDialog` as a temporary command palette summoned with a shortcut such as Ctrl/Cmd+K.
Command is built on Base UI Autocomplete, so the input and results share highlight state and keyboard navigation. Use it for actions — opening a document, navigating to a workspace area, changing a setting. Use Combobox instead when the person is selecting a value for a field rather than running an action; the interaction feels similar but the outcome is data entry, and Combobox integrates with Field and forms.
## Anatomy [#anatomy]
Command includes the root panel, search input with optional leading icon, scrollable content area, items with optional leading and trailing icons, an empty state, optional groups with labels, and separators. The dialog variant wraps the same pieces in a root, trigger, viewport, and popup with a visually hidden title.
All parts and Tailwind styles live in one `command.tsx` file and use named PascalCase exports. The content area caps at 320 px tall and scrolls internally, so a long command list never grows the page or the popup beyond its viewport.
## Behavior [#behavior]
Typing filters items. When you render `CommandItem` elements directly (the JSX style), Honest UI filters them by their `value` prop or visible text using a case-insensitive substring match. When you supply the root `items` prop instead, Base UI owns filtering and supports object values through `itemToStringValue`.
The first result is highlighted by default (`autoHighlight="always"`), so Enter always has a target. Groups, labels, and separators disappear during JSX filtering so results form one continuous list rather than scattered empty sections. The empty state appears only when no option remains.
Keep item labels action-oriented verbs ("Open documents", "Invite member"). Use the trailing icon slot for concise keyboard hints, not secondary descriptions that truncate on narrow panels.
## Keyboard [#keyboard]
| Key | Result |
| ----------------------------------------- | ------------------------------------------------------------------------------ |
| ArrowDown / ArrowUp | Move the highlight through results |
| Enter | Runs the highlighted item |
| Escape | Clears the query when the list is closed; closes the dialog variant while open |
| Home / End | Move the text cursor within the query |
Highlighting uses the combobox pattern: focus stays in the input while the highlighted option is announced through `aria-activedescendant`, so typing never loses focus.
## Accessibility [#accessibility]
`CommandInput` renders `type="search"` with role `combobox` and the default accessible name "Search commands." Pass a more specific `aria-label` when the scope is narrower, such as "Search billing actions," so screen-reader users know what the results will do. Results live in a `listbox`; each item is an `option` with `aria-selected` state managed for you.
The dialog content includes a visually hidden title (default "Command palette"); change it through the `title` prop so screen-reader users hear the same scope sighted users see in the placeholder.
If you add a global shortcut to open the palette, follow the pattern in the [command dialog example](#command-dialog): support both Control and Command, call `preventDefault` only for that shortcut, remove the listener when the component unmounts, and always keep a visible trigger — people who have never seen the shortcut need a discoverable way in.
The empty state matters here too: a blank panel after a typo reads as breakage. See [Don't do this](#dont-do-this).
Colors come from theme tokens, so the panel, highlight, and placeholder adapt to dark mode automatically. Item labels truncate rather than wrap; keep them short enough to survive narrow panels and localized text expansion.
## Installation [#installation]
Install the required dependency:
```bash
npm install @base-ui/react
```
Copy and paste the component into your project.
### components/ui/command.tsx
```tsx
"use client"
import * as React from "react"
import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete"
import { Dialog as DialogPrimitive } from "@base-ui/react/dialog"
import { cn } from "@/lib/utils"
type CommandContextValue = {
inputValue: string
usesItemsProp: boolean
}
const CommandContext = React.createContext(null)
function useCommandContext() {
const context = React.useContext(CommandContext)
if (!context) {
throw new Error("Command parts must be used within Command")
}
return context
}
function getTextContent(node: React.ReactNode): string {
return React.Children.toArray(node)
.map((child) => {
if (typeof child === "string" || typeof child === "number") {
return String(child)
}
if (React.isValidElement<{ children?: React.ReactNode }>(child)) {
return getTextContent(child.props.children)
}
return ""
})
.join(" ")
}
function matchesSearch(
value: unknown,
children: React.ReactNode,
query: string
) {
const searchableValue =
typeof value === "string" ? value : getTextContent(children)
return searchableValue
.toLocaleLowerCase()
.includes(query.trim().toLocaleLowerCase())
}
type CommandProps = Omit<
AutocompletePrimitive.Root.Props,
"items"
> & {
className?: string
items?: readonly ItemValue[]
}
function Command({
value: controlledValue,
defaultValue,
onValueChange,
items,
inline = true,
open = true,
autoHighlight = "always",
keepHighlight = true,
className,
children,
...props
}: CommandProps) {
const [uncontrolledValue, setUncontrolledValue] = React.useState(
typeof defaultValue === "string" ? defaultValue : ""
)
const inputValue =
typeof controlledValue === "string" ? controlledValue : uncontrolledValue
const handleValueChange = React.useCallback<
NonNullable["onValueChange"]>
>(
(nextValue, eventDetails) => {
if (controlledValue === undefined) {
setUncontrolledValue(nextValue)
}
onValueChange?.(nextValue, eventDetails)
},
[controlledValue, onValueChange]
)
const context = React.useMemo(
() => ({
inputValue,
usesItemsProp: items !== undefined,
}),
[inputValue, items]
)
return (
inline={inline}
open={open}
autoHighlight={autoHighlight}
keepHighlight={keepHighlight}
value={controlledValue}
defaultValue={defaultValue}
onValueChange={handleValueChange}
items={items}
{...props}
>
{children}
)
}
type CommandInputProps = Omit & {
leadingIcon?: React.ReactNode
size?: "sm" | "default" | "lg"
}
function CommandInput({
className,
leadingIcon,
size = "lg",
placeholder = "Search...",
autoFocus = true,
"aria-label": ariaLabel = "Search commands",
...props
}: CommandInputProps) {
return (
{leadingIcon ? (
{leadingIcon}
) : null}
)
}
type CommandContentProps = AutocompletePrimitive.List.Props
function CommandContent({ className, ...props }: CommandContentProps) {
return (
[data-slot=command-empty]]:hidden [&:not(:has([data-slot=command-group]))]:gap-[var(--hui-space-1)] [&:not(:has([data-slot=command-group]))]:py-[var(--hui-space-3)]",
className
)}
{...props}
/>
)
}
type CommandItemProps = AutocompletePrimitive.Item.Props & {
leadingIcon?: React.ReactNode
trailingIcon?: React.ReactNode
}
function CommandItem({
className,
children,
value: providedValue,
leadingIcon,
trailingIcon,
...props
}: CommandItemProps) {
const { inputValue, usesItemsProp } = useCommandContext()
const value =
providedValue !== undefined
? providedValue
: typeof children === "string"
? children
: undefined
if (
!usesItemsProp &&
inputValue &&
!matchesSearch(value, children, inputValue)
) {
return null
}
return (
{leadingIcon ? (
{leadingIcon}
) : null}
{children}
{trailingIcon ? (
{trailingIcon}
) : null}
)
}
type CommandEmptyProps = React.ComponentProps<"div">
function CommandEmpty({ className, ...props }: CommandEmptyProps) {
return (
)
}
type CommandGroupProps = AutocompletePrimitive.Group.Props
function CommandGroup({ children, className, ...props }: CommandGroupProps) {
const { inputValue, usesItemsProp } = useCommandContext()
if (!usesItemsProp && inputValue) return <>{children}
return (
{children}
)
}
type CommandLabelProps = AutocompletePrimitive.GroupLabel.Props
function CommandLabel({ className, ...props }: CommandLabelProps) {
const { inputValue, usesItemsProp } = useCommandContext()
if (!usesItemsProp && inputValue) return null
return (
)
}
type CommandSeparatorProps = AutocompletePrimitive.Separator.Props
function CommandSeparator({ className, ...props }: CommandSeparatorProps) {
const { inputValue, usesItemsProp } = useCommandContext()
if (!usesItemsProp && inputValue) return null
return (
)
}
function CommandDialog(props: DialogPrimitive.Root.Props) {
return
}
function CommandDialogTrigger(props: DialogPrimitive.Trigger.Props) {
return (
)
}
type CommandDialogContentProps = DialogPrimitive.Popup.Props & {
title?: string
width?: React.CSSProperties["width"]
}
function CommandDialogContent({
className,
children,
title = "Command palette",
width,
style,
...props
}: CommandDialogContentProps) {
return (
{title}
{children}
)
}
export {
Command,
CommandContent,
CommandDialog,
CommandDialogContent,
CommandDialogTrigger,
CommandEmpty,
CommandGroup,
CommandInput,
CommandItem,
CommandLabel,
CommandSeparator,
}
export type {
CommandContentProps,
CommandDialogContentProps,
CommandEmptyProps,
CommandGroupProps,
CommandInputProps,
CommandItemProps,
CommandLabelProps,
CommandProps,
CommandSeparatorProps,
}
```
Update the import paths to match your project setup.
## Usage [#usage]
```tsx
import {
Command,
CommandContent,
CommandEmpty,
CommandGroup,
CommandInput,
CommandItem,
CommandLabel,
} from "@/components/ui/command";
```
```tsx
No matching commands.
Workspace
New document
Workspace settings
```
Always include `CommandEmpty`. It renders only when filtering leaves no results, so there is no cost to having it and no excuse to omit it.
## Don't do this [#dont-do-this]
### No guidance when nothing matches [#no-guidance-when-nothing-matches]
```tsx
// Bad
{items.map((item) => (
{item.label}
))}
```
```tsx
// Good
No matches for “{query}”. Try a different term or browse all commands.
{items.map((item) => (
{item.label}
))}
```
A blank panel after a typo looks like the app froze, and people cannot tell whether their query matched nothing or the list failed to load. State what happened and what to try next — the empty string is part of the interface, not an edge case.
### Destructive actions with no guardrail [#destructive-actions-with-no-guardrail]
```tsx
// Bad
Delete workspace
```
```tsx
// Good
setConfirmOpen(true)}>
Delete workspace…
```
A palette makes destructive actions dangerously easy: one typed prefix, one press of Enter. Route irreversible commands through a confirmation step instead of executing immediately. The ellipsis in the label is a small cue that more will be asked before anything happens.
### A palette nobody can find [#a-palette-nobody-can-find]
```tsx
// Bad
useEffect(() => {
// ⌘K opens the palette — nothing rendered anywhere
}, [])
```
```tsx
// Good
}>
Search actions ⌘K
```
Shortcuts are invisible until discovered. If the trigger exists nowhere on screen, people who never read your docs — which is most people — never learn the feature exists. Render a visible trigger with the shortcut hint next to it and teach the shortcut by exposure.
## Examples [#examples]
### Inline command list [#inline-command-list]
Grouping, filtering, keyboard hints in the trailing slot, icons, and visible action feedback announced through a polite live region.
```tsx
"use client"
import * as React from "react"
import {
File as FileIcon,
Palette as PaletteIcon,
Search as SearchIcon,
Settings as SettingsIcon,
User as UserIcon,
} from "honestui/icons"
import {
Command,
CommandContent,
CommandEmpty,
CommandGroup,
CommandInput,
CommandItem,
CommandLabel,
CommandSeparator,
} from "@/components/honest-ui/ui/command"
export function CommandDemo() {
const [lastAction, setLastAction] = React.useState("No command selected")
return (
}
placeholder="Search commands..."
/>
No matching commands.
Navigation
}
trailingIcon={G then D}
onClick={() => setLastAction("Opened documents")}
>
Open documents
}
onClick={() => setLastAction("Opened account")}
>
Open account
Preferences
}
onClick={() => setLastAction("Opened appearance")}
>
Change appearance
}
onClick={() => setLastAction("Opened settings")}
>
Open settings
{lastAction}
)
}
```
### Command dialog [#command-dialog]
A controlled palette bound to Ctrl/Cmd+K, with a visible trigger, a scoped hidden title, and closing after each command runs.
```tsx
"use client"
import * as React from "react"
import {
Command as CommandIcon,
File as FileIcon,
Search as SearchIcon,
Settings as SettingsIcon,
User as UserIcon,
} from "honestui/icons"
import { Button } from "@/components/honest-ui/ui/button"
import {
Command,
CommandContent,
CommandDialog,
CommandDialogContent,
CommandDialogTrigger,
CommandEmpty,
CommandGroup,
CommandInput,
CommandItem,
CommandLabel,
} from "@/components/honest-ui/ui/command"
export function CommandDialogDemo() {
const [open, setOpen] = React.useState(false)
const [lastAction, setLastAction] = React.useState("No command selected")
React.useEffect(() => {
function handleKeyDown(event: KeyboardEvent) {
if (event.key.toLocaleLowerCase() === "k" && (event.metaKey || event.ctrlKey)) {
event.preventDefault()
setOpen((currentOpen) => !currentOpen)
}
}
document.addEventListener("keydown", handleKeyDown)
return () => document.removeEventListener("keydown", handleKeyDown)
}, [])
function runCommand(message: string) {
setLastAction(message)
setOpen(false)
}
return (
}>
Open command palette
⌘K
}
placeholder="Search workspace commands..."
/>
No matching commands.
Workspace
}
onClick={() => runCommand("Opened a new document")}
>
New document
}
onClick={() => runCommand("Opened team members")}
>
View team members
}
onClick={() => runCommand("Opened workspace settings")}
>
Workspace settings
{lastAction}
)
}
```
## API reference [#api-reference]
### `Command` [#command]
Forwards Base UI Autocomplete root props plus:
| Prop | Values | Default |
| ------------------------------------------ | ------------------------ | ------------ |
| `items` | readonly array | — |
| `value` / `defaultValue` / `onValueChange` | string | uncontrolled |
| `open` | boolean | `true` |
| `inline` | boolean | `true` |
| `autoHighlight` | `"always"`, `"never"`, … | `"always"` |
| `keepHighlight` | boolean | `true` |
Passing `items` switches filtering from Honest UI's JSX fallback to Base UI's own item filtering.
### `CommandInput` [#commandinput]
Accepts Base UI Autocomplete input props plus:
| Prop | Values | Default |
| ------------- | --------------------- | ------------------- |
| `leadingIcon` | ReactNode | — |
| `size` | `sm`, `default`, `lg` | `lg` |
| `placeholder` | string | `"Search..."` |
| `autoFocus` | boolean | `true` |
| `aria-label` | string | `"Search commands"` |
### `CommandItem` [#commanditem]
Accepts Base UI item props plus `leadingIcon` and `trailingIcon`. Without an explicit `value`, a plain-string child becomes the filterable value. `onClick` runs on Enter and on click.
### Other parts [#other-parts]
`CommandContent`, `CommandEmpty`, `CommandGroup`, `CommandLabel`, and `CommandSeparator` accept their matching Base UI element props. During JSX filtering, groups, labels, and separators hide themselves once a query is active.
### Dialog parts [#dialog-parts]
`CommandDialog` and `CommandDialogTrigger` forward Base UI Dialog root and trigger props. `CommandDialogContent` forwards popup props plus:
| Prop | Values | Default |
| ------- | --------- | ------------------- |
| `title` | string | `"Command palette"` |
| `width` | CSS width | `540px`, max `90vw` |
See the [Base UI Autocomplete API](https://base-ui.com/react/components/autocomplete#api-reference) and [Base UI Dialog API](https://base-ui.com/react/components/dialog#api-reference) for controlled state, item collections, filtering, and focus behavior.