# Command
> Search and run actions from an inline list or command palette.
Source: https://www.honestui.com/docs/components/command
---
title: Command
description: Search and run actions from an inline list or command palette.
links:
doc: https://base-ui.com/react/components/autocomplete#api-reference
---
```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
Use Command to help people find and run actions from a compact, keyboard-oriented list. It works inline for a persistent command browser or inside `CommandDialog` for a temporary command palette.
Command is built on Base UI Autocomplete, so the input and results share highlight state and keyboard navigation. Use it for actions such as opening a document, navigating to a workspace area, or changing a setting. Use Combobox instead when the person is selecting a value for a field rather than running an action.
## Anatomy
Command includes the root panel, search input, scrollable content, items, an empty state, optional groups and labels, and separators. The dialog variant adds a root, trigger, viewport, and popup. All parts and Tailwind styles live in one `command.tsx` file and use named PascalCase exports.
## Behavior
Typing filters JSX items by their `value` or visible text. When you supply the root `items` prop, Base UI owns filtering and supports object values through `itemToStringValue`. The first result is highlighted by default, arrow keys move the highlight, Enter runs the highlighted item, and Escape closes the dialog variant.
Groups and separators disappear during the built-in JSX filtering fallback so results form one continuous list. The empty state appears only when no option remains. Keep item labels action-oriented and use the optional trailing area for concise keyboard hints rather than secondary descriptions.
## Accessibility
`CommandInput` has the default accessible name “Search commands.” Pass a more specific `aria-label` when the command scope is narrower. The dialog content includes a visually hidden title; change its `title` prop so screen-reader users hear the same scope as sighted users.
Base UI manages the combobox, listbox, option, dialog, focus, and keyboard relationships. If you add a global shortcut, support both Control and Command where appropriate, prevent the browser default only for that shortcut, remove the listener when the component unmounts, and keep a visible trigger for people who do not know the shortcut.
## Installation
```bash
npx honestui@latest add command
```
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
```tsx
import {
Command,
CommandContent,
CommandEmpty,
CommandGroup,
CommandInput,
CommandItem,
CommandLabel,
} from "@/components/ui/command";
```
```tsx
No matching commands.
Workspace
New document
Workspace settings
```
## Examples
The inline example demonstrates grouping, filtering, keyboard hints, icons, and visible action feedback. The dialog example adds a persistent trigger and the familiar Control/Command+K shortcut.
### Inline command list
```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
```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
`Command` forwards Base UI Autocomplete root props and adds a panel `className`. `CommandInput` accepts Base UI input props plus `leadingIcon` and `size`. `CommandItem` accepts Base UI item props plus `leadingIcon` and `trailingIcon`.
`CommandDialog` and `CommandDialogTrigger` forward their matching Base UI Dialog props. `CommandDialogContent` accepts popup props plus `title` and `width`. 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.