Command

Open

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
input	command-input
item	command-item
list	command-list
separator	command-separator
shortcut	command-shortcut

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}>
  <Command>
    {/* Command content */}
  </Command>
</CommandDialog>

API Reference

Command

Prop	Default	Type	Description
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.

CommandInput

Search input with optional startIcon.

CommandList

Scrollable list container (uses ScrollArea internally).

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.