Command

Open

Dialog

󰕈

Inline

Small

󰕋

Medium

󰕈

Large

󰕇

Sizes

Contract

Overview

Machine-readable contract from Component Spec.

component: commandexport: Commandversion: 1attributes: data-refineui=command

Anatomy

Part	data-refineui
root	command
empty	command-empty
group	command-group
group_heading	command-group-heading
indicator	command-indicator
input	command-input
item	command-item
list	command-list
separator	command-separator
shortcut	command-shortcut

Variants

Axis	Values
size	sm, md, lg

States

Scope	Category	Values
component	pseudo	focus-visible
component	component	data-state: disabled, active, default
component	environment	forced-colors, dir

Accessibility

Slot	Element	Role	Required attributes
command-item	div	option	aria-selected: required=true, type: boolean

Keyboard

Key	Action	Native
ArrowDown	next-trigger	—
ArrowUp	previous-trigger	—
Home	first-trigger	—
End	last-trigger	—
Enter	activate	—

Focus

Section	Property	Value
visual	required	true
visual	selector	:focus-visible

Layout

Property	Value
direction	logical
rtl	true

Installation

npmyarnpnpmbun

npm install @refineui/react @refineui/tokens

Usage

import {
  Command,
  CommandInput,
  CommandList,
  CommandEmpty,
  CommandGroup,
  CommandGroupHeading,
  CommandItem,
  CommandSeparator
} from "@refineui/react";

<Command>
  <CommandInput placeholder="Search commands..." />
  <CommandList>
    <CommandEmpty>No results found.</CommandEmpty>
    <CommandGroup>
      <CommandGroupHeading>File</CommandGroupHeading>
      <CommandItem value="new" onSelect={() => handleNew()}>
        New File
      </CommandItem>
      <CommandItem value="open">Open</CommandItem>
    </CommandGroup>
    <CommandSeparator />
    <CommandGroup>
      <CommandGroupHeading>Edit</CommandGroupHeading>
      <CommandItem value="copy">Copy</CommandItem>
      <CommandItem value="paste">Paste</CommandItem>
    </CommandGroup>
  </CommandList>
</Command>

<CommandDialog open={isOpen} onOpenChange={setIsOpen}>
  <CommandInput placeholder="Search commands..." />
  <CommandList>{/* Same groups and items as above */}</CommandList>
</CommandDialog>

API Reference

Command

Prop	Default	Type	Description
size	"md"	"sm" | "md" | "lg"	Density of the search field, results panel radius, and item rows — same tiers as SearchField.
value	—	string	Controlled search query.
defaultValue	—	string	Uncontrolled initial search query.
onValueChange	—	(search: string) => void	Event handler when search changes.
shouldFilter	true	boolean	When true, filters items by search text.
filter	—	CommandFilter	Custom score function (return 0 to hide).
selectedValue	—	string	Controlled highlighted item value.
defaultSelectedValue	—	string	Uncontrolled initial highlighted item.
onSelectedValueChange	—	(value: string) => void	Event handler when highlighted item changes.
label	—	string	Accessible name (`aria-label`).

CommandDialog

Command in a Dialog overlay.

Prop	Default	Type	Description
open	—	boolean	Controlled open state.
onOpenChange	—	(open: boolean) => void	Event handler when open state changes.
commandProps	—	CommandProps	Props forwarded to inner Command. The Command size defaults to "lg" here; `size` on CommandDialog itself sets the dialog width.

CommandInput

Search input with optional startIcon.

CommandList

List container that grows with its results up to a max height, then scrolls (uses ScrollArea internally). A single highlight slides to the selected item, and the height animates as results filter; both respect prefers-reduced-motion.

CommandEmpty

Shown when no items match.

CommandGroup

Groups related items.

CommandGroupHeading

Heading for a group.

CommandSeparator

Visual divider.

CommandItem

Prop	Default	Type	Description
value	—	string	Unique value for filtering and selection (required).
keywords	—	string[]	Extra strings for default filter.
onSelect	—	(value: string) => void	Called when activated (click/Enter).
forceMount	false	boolean	Keep mounted when filtered out.
startIcon	—	ReactNode	Leading icon.
endIcon	—	ReactNode	Trailing icon.
shortcut	—	ReactNode	Keyboard shortcut hint.