Command

Organism

Cmd+K search: navigation, actions, recent items.

src/organisms/command

View in Overlays & feedback

Playground

Every control sets a real prop of CommandProps. The JSX below updates as you go.

Web

iOS

Android

Props

placeholder

string

query

string

embedded

boolean

footer

boolean

JSX · CommandProps

<Command placeholder="Search or jump to…" footer />

Variants

4 examples from src/organisms/command/command.md, each rendered live from its own JSX.

Inline

<Command

  groups={[

    { heading: "Actions", items: [

      { label: "New File" },

      { label: "Open File" },

      { label: "Save" }

    ] },

    { heading: "Navigation", items: [

      { label: "Go to Dashboard" },

      { label: "Go to Settings" }

] }

]}

/>

↑↓ move

↵ open

esc close

Footer with key hints

<Command

  footer

  groups={[

    { heading: "Actions", items: [

      { label: "New File" },

      { label: "Open File" },

      { label: "Save" }

    ] },

    { heading: "Navigation", items: [

      { label: "Go to Dashboard" },

      { label: "Go to Settings" }

] }

]}

/>

Embedded search

<Card flush>

  <Command embedded filtered defaultQuery="universal" groups={[

    { heading: "Guides", items: [

      { label: "Canvas", description: "A universal interface kit" }

] }

  ]} />

</Card>

Filtering

Typing narrows the rows; defaultQuery seeds the filter (here only the file actions match), and groups left with no match drop out.

<Command

  defaultQuery="file"

  groups={[

    { heading: "Actions", items: [

      { label: "New File" },

      { label: "Open File" },

      { label: "Save" }

    ] },

    { heading: "Navigation", items: [

      { label: "Go to Dashboard" },

      { label: "Go to Settings" }

] }

]}

/>

Anatomy

1

Panel

2

Search field

3

Group label

4

Item

5

Active item

6

Footer hints

Dimmed parts appear only in some states or variants.

Props

21 props on CommandProps, grouped as they are declared in source. Required props are marked *.

Prop

Type

Default

Description

Props

21 props

placeholder

string

"Search commands..."

Prompt shown in the empty search input.

accessibilityLabel

string

–

Accessible purpose for the search input and result list. Defaults to the search placeholder. Supply this when the placeholder does not explain the task.

query

string

–

The text typed into the search input (CONTROLLED). Filters the rows to the labels matching it (case-insensitive). Omit and use defaultQuery for uncontrolled use: a bare Command is searchable out of the box.

defaultQuery

string

–

Initial query for uncontrolled use.

onQueryChange

(query: string) => void

–

Fired with the new query on each keystroke (both modes).

groups

CommandGroup[]

–

Grouped result rows.

filtered

boolean

false

Groups are already filtered and ranked by the owner; preserve their order and contents.

embedded

boolean

false

Fill the parent and inherit its surface, for composition inside a Dialog or Drawer. Ignored with trigger.

autoFocus

boolean

false

Focus the inline search field after mounting, allowing the containing overlay to capture its opener first.

onKeyPress

TextInputProps["onKeyPress"]

–

Input keyboard handler, called before built-in navigation. preventDefault cancels built-in handling.

emptyMessage

string

–

Content shown when there are no result rows, including an empty query.

active

number

–

Flat index of the highlighted row (CONTROLLED), counted across the visible (query-matching) rows. Omit for uncontrolled use.

defaultActive

number

–

Initial highlighted row for uncontrolled use (hovering a row moves it, typing resets it to the first match).

open

boolean

false

Controlled open state. Omit for uncontrolled (the search trigger toggles it).

defaultOpen

boolean

false

Render the palette open initially for uncontrolled use (selecting a row closes it).

onOpenChange

(open: boolean) => void

–

Fired when the open state changes.

trigger

boolean

false

Render a collapsed full-width search trigger above the palette (a search glyph + "Search..." + a trailing kbd cap). The palette card still renders inline below the trigger (gated by open), mirroring how Dropdown shows its trigger plus the open menu in the docs.

footer

boolean

false

Append a footer hint bar below the list (↑ ↓ to navigate, ↵ to select, esc to close).

onSelect

(item: CommandItem, index: number) => void

–

Called with the chosen item and its flat index (within the visible, query-matching rows) when a row is pressed.

testID

string

–

E2E hook forwarded to the root element; the scrolling results list gets ${testID}-results.

style

StyleProp<ViewStyle>

–

Outer layout composition only (width/flex within a parent), never a restyle hook.

Accessibility and keyboard

Keyboard

ArrowDown

Opens the list

ArrowUp

ArrowDown

Moves through options

Enter

Commits the active option

Escape

Closes the list, keeps the text

Semantics

Roles

button

group

option

search

States

expanded

selected

ARIA on web

aria-activedescendant

aria-controls

aria-expanded

aria-label

aria-selected

Below the platform minimum, the touch area grows to 44 pt on iOS and 48 dp on Android without moving the layout.

From the docs

In glass mode the triggered palette is a functional-layer glass card under the search bar, with its own search field; the search editor keeps focus while typing filters the rows. Solid mode paints the skin's own palette.

The search row is a real input: typing filters the grouped rows to the matching labels, and a query that matches nothing shows a muted "No results" row.

Use embedded inside a Dialog or Drawer to inherit its surface and fill its bounds. It has no effect when trigger is set. Long results scroll within the palette. autoFocus focuses the inline field after the containing overlay captures its opener, so closing restores the original control. onKeyPress runs before built-in navigation; call preventDefault() to handle an application shortcut.

Platform skins

The playground's props on each platform: same tree, native shapes, type and touch sizes.

↑↓ move

↵ open

esc close

Web

control 10 · field 10 · card 16 · Instrument Sans

↑↓ move

↵ open

esc close

iOS

capsule controls · field 8 · card 12 · SF Pro · 44 pt

↑↓ move

↵ open

esc close

Android

Material 3 stadium · field 4 · card 12 · Roboto · 48 dp

Usage

<Command

  trigger

  groups={[

    { heading: "Actions", items: [

      { label: "New File", icon: "file", shortcut: "Ctrl+N" },

      { label: "Open File", icon: "folder", shortcut: "Ctrl+O" },

      { label: "Save", icon: "save", shortcut: "Ctrl+S" }

    ] },

    { heading: "Navigation", items: [

      { label: "Go to Dashboard", icon: "arrowRight" },

      { label: "Go to Settings", icon: "arrowRight" }

] }

]}

/>

The search row is a real input: typing filters the grouped rows to the matching labels, and a query that matches nothing shows a muted "No results" row.

On every platform the palette is the v4 card: 520 wide at an 18-pixel corner, a 48-pixel search row with an esc cap over a hairline, mono eyebrows over 38-pixel rows (44 on iOS, 48 on Android) with quiet icons and mono shortcuts, the accent's soft wash under the active row, and an optional footer of mono hints. Neither iOS nor Android ships a command palette, so both take this look in their own face.

In glass mode the triggered palette is a functional-layer glass card under the search bar, with its own search field; the search editor keeps focus while typing filters the rows. Solid mode paints the skin's own palette.

Tokens

Read from the playground render. Values follow the scheme and the ion hue.

--bf

--bg2

--fd

--fm

--ft

--gl

--ion-soft

--ion-tx

--ln

--ln2

--scrim

--sf3

--sh-lg

--tx

--tx3

Command

Playground

Variants

Anatomy

Props

Accessibility and keyboard

Platform skins

Usage

Tokens

Related components