Command

Filter and execute actions from a keyboard-friendly list.

View component source ↗

Preview

Example

A minimal example to get started.

Installation

Install this component and its dependencies in a project initialized with shadcn.

pnpm dlx shadcn@latest add https://ui.hyunjoon.net/r/command.json

Usage

This is the basic example. Use the Code tab above for the selected example. Adjust import aliases to match your project.

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

export default function Example() {
  return (
    <Command className="max-w-sm rounded-lg border">
      <CommandInput placeholder="Search actions…" />
      <CommandList>
        <CommandEmpty>No actions found.</CommandEmpty>
        <CommandGroup heading="Suggestions">
          <CommandItem>Open calendar</CommandItem>
          <CommandItem>Search projects</CommandItem>
          <CommandItem>View settings</CommandItem>
        </CommandGroup>
      </CommandList>
    </Command>
  );
}

API reference

Derived from the installed component types. Native DOM props are also supported where applicable. A dash means no explicit default is documented. Some props depend on the selected mode.

Command

Command properties
Prop	Type	Default	Description
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`defaultValue`	string \| (readonly string[] & string) \| undefined string \| (readonly string[] & string) \| undefined	`—`	Optional default item value when it is initially rendered.
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`onFocus`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLDivElement, Element> \| undefined React.ChangeEventHandler<HTMLDivElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLDivElement> \| undefined React.KeyboardEventHandler<HTMLDivElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLDivElement> \| undefined React.MouseEventHandler<HTMLDivElement> \| undefined	`—`	Called when the element is activated.
`asChild`	boolean \| undefined boolean \| undefined	`—`	Composes this component with its child element.
`label`	string \| undefined string \| undefined	`—`	Accessible label for this command menu. Not shown visibly.
`shouldFilter`	boolean \| undefined boolean \| undefined	`—`	Optionally set to `false` to turn off the automatic filtering and sorting. If `false`, you must conditionally render valid items based on the search query yourself.
`filter`	CommandFilter \| undefined CommandFilter \| undefined	`—`	Custom filter function for whether each command menu item should matches the given search query. It should return a number between 0 and 1, with 1 being the best match and 0 being hidden entirely. By default, uses the `command-score` library.
`value`	string \| undefined string \| undefined	`—`	Optional controlled state of the selected command menu item.
`onValueChange`	((value: string) => void) \| undefined ((value: string) => void) \| undefined	`—`	Event handler called when the selected item of the menu changes.
`loop`	boolean \| undefined boolean \| undefined	`—`	Optionally set to `true` to turn on looping around when using the arrow keys.
`disablePointerSelection`	boolean \| undefined boolean \| undefined	`—`	Optionally set to `true` to disable selection via pointer events.
`vimBindings`	boolean \| undefined boolean \| undefined	`—`	Set to `false` to disable ctrl+n/j/p/k shortcuts. Defaults to `true`.
`ref`	React.Ref<HTMLDivElement> \| undefined React.Ref<HTMLDivElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).

CommandDialog

CommandDialog properties
Prop	Type	Default	Description
`modal`	boolean \| "trap-focus" \| undefined boolean \| "trap-focus" \| undefined	`true`	Determines if the dialog enters a modal state when open. - `true`: user interaction is limited to just the dialog: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. - `'trap-focus'`: focus is trapped inside the dialog, but document page scroll is not locked and pointer interactions outside of it remain enabled. When `modal` is `true` or `'trap-focus'`, render `<Dialog.Close>` inside `<Dialog.Popup>` so touch screen readers can escape the popup.
`disablePointerDismissal`	boolean \| undefined boolean \| undefined	`false`	Determines whether the dialog should close on outside clicks.
`onOpenChange`	((open: boolean, eventDetails: DialogRoot.ChangeEventDetails) => void) \| undefined ((open: boolean, eventDetails: DialogRoot.ChangeEventDetails) => void) \| undefined	`—`	Event handler called when the dialog is opened or closed.
`actionsRef`	React.RefObject<DialogRootActions \| null> \| undefined React.RefObject<DialogRootActions \| null> \| undefined	`—`	A ref to imperative actions. - `unmount`: When specified, the dialog will not be unmounted when closed. Instead, the `unmount` function must be called to unmount the dialog manually. Useful when the dialog's animation is controlled by an external library. - `close`: Closes the dialog imperatively when called.
`handle`	DialogHandle<unknown> \| undefined DialogHandle<unknown> \| undefined	`—`	A handle to associate the dialog with a trigger. If specified, allows external triggers to control the dialog's open state. Can be created with the Dialog.createHandle() method.
`open`	boolean \| undefined boolean \| undefined	`—`	Whether the dialog is currently open.
`defaultOpen`	boolean \| undefined boolean \| undefined	`false`	Whether the dialog is initially open. To render a controlled dialog, use the `open` prop instead.
`onOpenChangeComplete`	((open: boolean) => void) \| undefined ((open: boolean) => void) \| undefined	`—`	Event handler called after any animations complete when the dialog is opened or closed.
`triggerId`	string \| null \| undefined string \| null \| undefined	`—`	ID of the trigger that the dialog is associated with. This is useful in conjunction with the `open` prop to create a controlled dialog. There's no need to specify this prop when the popover is uncontrolled (that is, when the `open` prop is not set).
`defaultTriggerId`	string \| null \| undefined string \| null \| undefined	`—`	ID of the trigger that the dialog is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open dialog.
`title`	string \| undefined string \| undefined	`"Command Palette"`	Title presented to the user.
`description`	string \| undefined string \| undefined	`"Search for a command to run..."`	Supporting description for the component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`showCloseButton`	boolean \| undefined boolean \| undefined	`false`	Displays the popup's close button.
`children`Required	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.

CommandInput

CommandInput properties
Prop	Type	Default	Description
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLInputElement> \| undefined React.FocusEventHandler<HTMLInputElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLInputElement> \| undefined React.FocusEventHandler<HTMLInputElement> \| undefined	`—`	Called when the control loses focus.
`onKeyDown`	React.KeyboardEventHandler<HTMLInputElement> \| undefined React.KeyboardEventHandler<HTMLInputElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLInputElement> \| undefined React.MouseEventHandler<HTMLInputElement> \| undefined	`—`	Called when the element is activated.
`disabled`	boolean \| undefined boolean \| undefined	`—`	Prevents user interaction.
`name`	string \| undefined string \| undefined	`—`	Field name used in form data.
`alt`	string \| undefined string \| undefined	`—`	Accessible text alternative for the image.
`src`	string \| undefined string \| undefined	`—`	URL of the displayed resource.
`multiple`	boolean \| undefined boolean \| undefined	`—`	Allows more than one value to be selected.
`max`	string \| number \| undefined string \| number \| undefined	`—`	Maximum allowed value.
`min`	string \| number \| undefined string \| number \| undefined	`—`	Minimum allowed value.
`step`	string \| number \| undefined string \| number \| undefined	`—`	Increment between valid values.
`required`	boolean \| undefined boolean \| undefined	`—`	Whether the user must provide a value before form submission.
`checked`	boolean \| undefined boolean \| undefined	`—`	Current checked state when controlled.
`maxLength`	number \| undefined number \| undefined	`—`	Maximum number of input characters.
`placeholder`	string \| undefined string \| undefined	`—`	Hint shown when the control has no value.
`asChild`	boolean \| undefined boolean \| undefined	`—`	Composes this component with its child element.
`value`	string \| undefined string \| undefined	`—`	Optional controlled state for the value of the search input.
`onValueChange`	((search: string) => void) \| undefined ((search: string) => void) \| undefined	`—`	Event handler called when the search value changes.
`ref`	React.Ref<HTMLInputElement> \| undefined React.Ref<HTMLInputElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).

CommandList

CommandList properties
Prop	Type	Default	Description
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`onFocus`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLDivElement, Element> \| undefined React.ChangeEventHandler<HTMLDivElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLDivElement> \| undefined React.KeyboardEventHandler<HTMLDivElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLDivElement> \| undefined React.MouseEventHandler<HTMLDivElement> \| undefined	`—`	Called when the element is activated.
`asChild`	boolean \| undefined boolean \| undefined	`—`	Composes this component with its child element.
`label`	string \| undefined string \| undefined	`—`	Accessible label for this List of suggestions. Not shown visibly.
`ref`	React.Ref<HTMLDivElement> \| undefined React.Ref<HTMLDivElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).

CommandEmpty

CommandEmpty properties
Prop	Type	Default	Description
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`onFocus`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLDivElement, Element> \| undefined React.ChangeEventHandler<HTMLDivElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLDivElement> \| undefined React.KeyboardEventHandler<HTMLDivElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLDivElement> \| undefined React.MouseEventHandler<HTMLDivElement> \| undefined	`—`	Called when the element is activated.
`asChild`	boolean \| undefined boolean \| undefined	`—`	Composes this component with its child element.
`ref`	React.Ref<HTMLDivElement> \| undefined React.Ref<HTMLDivElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).

CommandGroup

CommandGroup properties
Prop	Type	Default	Description
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`onFocus`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLDivElement, Element> \| undefined React.ChangeEventHandler<HTMLDivElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLDivElement> \| undefined React.KeyboardEventHandler<HTMLDivElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLDivElement> \| undefined React.MouseEventHandler<HTMLDivElement> \| undefined	`—`	Called when the element is activated.
`asChild`	boolean \| undefined boolean \| undefined	`—`	Composes this component with its child element.
`heading`	React.ReactNode React.ReactNode	`—`	Optional heading to render for this group.
`value`	string \| undefined string \| undefined	`—`	If no heading is provided, you must provide a value that is unique for this group.
`forceMount`	boolean \| undefined boolean \| undefined	`—`	Whether this group is forcibly rendered regardless of filtering.
`ref`	React.Ref<HTMLDivElement> \| undefined React.Ref<HTMLDivElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).

CommandItem

CommandItem properties
Prop	Type	Default	Description
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`onFocus`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLDivElement, Element> \| undefined React.ChangeEventHandler<HTMLDivElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLDivElement> \| undefined React.KeyboardEventHandler<HTMLDivElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLDivElement> \| undefined React.MouseEventHandler<HTMLDivElement> \| undefined	`—`	Called when the element is activated.
`asChild`	boolean \| undefined boolean \| undefined	`—`	Composes this component with its child element.
`disabled`	boolean \| undefined boolean \| undefined	`—`	Whether this item is currently disabled.
`onSelect`	((value: string) => void) \| undefined ((value: string) => void) \| undefined	`—`	Event handler for when this item is selected, either via click or keyboard selection.
`value`	string \| undefined string \| undefined	`—`	A unique value for this item. If no value is provided, it will be inferred from `children` or the rendered `textContent`. If your `textContent` changes between renders, you _must_ provide a stable, unique `value`.
`keywords`	string[] \| undefined string[] \| undefined	`—`	Optional keywords to match against when filtering.
`forceMount`	boolean \| undefined boolean \| undefined	`—`	Whether this item is forcibly rendered regardless of filtering.
`ref`	React.Ref<HTMLDivElement> \| undefined React.Ref<HTMLDivElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).

CommandShortcut

CommandShortcut properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLSpanElement> \| undefined React.Ref<HTMLSpanElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLSpanElement> \| undefined React.FocusEventHandler<HTMLSpanElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLSpanElement> \| undefined React.FocusEventHandler<HTMLSpanElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLSpanElement, Element> \| undefined React.ChangeEventHandler<HTMLSpanElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLSpanElement> \| undefined React.KeyboardEventHandler<HTMLSpanElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLSpanElement> \| undefined React.MouseEventHandler<HTMLSpanElement> \| undefined	`—`	Called when the element is activated.

CommandSeparator

CommandSeparator properties
Prop	Type	Default	Description
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLDivElement, Element> \| undefined React.ChangeEventHandler<HTMLDivElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLDivElement> \| undefined React.KeyboardEventHandler<HTMLDivElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLDivElement> \| undefined React.MouseEventHandler<HTMLDivElement> \| undefined	`—`	Called when the element is activated.
`asChild`	boolean \| undefined boolean \| undefined	`—`	Composes this component with its child element.
`alwaysRender`	boolean \| undefined boolean \| undefined	`—`	Whether this separator should always be rendered. Useful if you disable automatic filtering.
`ref`	React.Ref<HTMLDivElement> \| undefined React.Ref<HTMLDivElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).

Usage notes

Organize related commands into groups. Handle onSelect on an item to connect it to a real application action.