Command

Fast, composable command menu built on top of the Base UI Autocomplete primitive.
1<Flex style={{ width: 400 }}>
2  <Command>
3    <Command.Panel>
4      <Command.Input placeholder="Search..." />
5      <Command.List>
6        <Command.Empty>No results found.</Command.Empty>
7        <Command.Group>
8          <Command.Label>Actions</Command.Label>
9          <Command.Item leadingIcon={<TransformIcon />}>
10            Create AOI...
11            <Command.Shortcut>
12              <span>⌘</span>
13              <span>⇧</span>
14              <span>A</span>
15            </Command.Shortcut>

Anatomy

Import and assemble the component:

1import { Command } from "@raystack/apsara";
2

3<Command>
4  <Command.Panel>
5    <Command.Input />
6    <Command.List>
7      <Command.Empty>No results found.</Command.Empty>
8      <Command.Group>
9        <Command.Label>Suggestions</Command.Label>
10        <Command.Item>Item</Command.Item>
11      </Command.Group>
12      <Command.Separator />
13    </Command.List>
14    <Command.Footer />
15  </Command.Panel>
16</Command>

For a command palette launched by a keyboard shortcut, wrap Command in Command.Dialog:

1<Command.Dialog>
2  <Command.Dialog.Trigger>Open</Command.Dialog.Trigger>
3  <Command.Dialog.Content>
4    <Command>
5      <Command.Input />
6      <Command.List>{/* ... */}</Command.List>
7    </Command>
8  </Command.Dialog.Content>
9</Command.Dialog>

Built-in auto-search

By default, Command filters Command.Item children based on the input value — the same behavior as our Combobox. No items prop is required. Matching is case-insensitive and looks at both the value prop and the item's text content.

Pass the items prop to opt out of this built-in behavior and delegate filtering to Base UI's internal logic (or your own filter function).

API Reference

Root

The root element owns the input value, the list of items, and the context used by every sub-component.

Prop

Type

Panel

A styled card wrapper that gives the command menu its popover look when used inline (outside of Command.Dialog).

Prop

Type

Input

Text input that drives the search. Accepts the same props as InputField and defaults to a magnifying-glass leading icon.

Prop

Type

List

Scrollable container for groups and items. Renders with role="listbox".

Prop

Type

Empty

Rendered when no items are visible (all filtered out, or the list is empty). Automatically hidden when the list contains at least one item.

Prop

Type

Item

A selectable entry. When value is omitted and children is a string, the string is used as the value. onClick fires on pointer click and on keyboard Enter when the item is highlighted.

Prop

Type

Group

Groups related items. The group and its children are hidden automatically while the user is searching.

Prop

Type

Label

Renders a label inside Command.Group.

Prop

Type

Separator

Visual divider between groups. Hidden while searching.

Prop

Type

Shortcut

A <kbd> element for keyboard hints inline with items or the footer.

Prop

Type

Footer

Optional footer slot rendered below the list.

Prop

Type

Dialog

Command.Dialog is an alias for the Base UI Dialog root, plus a composed Content sub-component that provides the portal, backdrop, viewport, and popup.

Prop

Type

Dialog Content

Prop

Type

Examples

Basic

A command menu with a flat list of items. Type to filter.

1<Flex style={{ width: 420 }}>
2  <Command>
3    <Command.Panel>
4      <Command.Input placeholder="Search..." />
5      <Command.List>
6        <Command.Empty>No results found.</Command.Empty>
7        <Command.Item>Calendar</Command.Item>
8        <Command.Item>Search Emoji</Command.Item>
9        <Command.Item>Calculator</Command.Item>
10        <Command.Item>Profile</Command.Item>
11        <Command.Item>Billing</Command.Item>
12        <Command.Item>Settings</Command.Item>
13      </Command.List>
14    </Command.Panel>
15  </Command>

Groups and Separators

Organise items into groups with labels and visual separators. Groups, labels, and separators are hidden automatically while searching.

1<Flex style={{ width: 420 }}>
2  <Command>
3    <Command.Panel>
4      <Command.Input placeholder="Type a command or search..." />
5      <Command.List>
6        <Command.Empty>No results found.</Command.Empty>
7        <Command.Group>
8          <Command.Label>Suggestions</Command.Label>
9          <Command.Item>Calendar</Command.Item>
10          <Command.Item>Search Emoji</Command.Item>
11          <Command.Item>Calculator</Command.Item>
12        </Command.Group>
13        <Command.Separator />
14        <Command.Group>
15          <Command.Label>Settings</Command.Label>

With Icons

Pass a leadingIcon on Command.Item to render an icon before the label.

1<Flex style={{ width: 420 }}>
2  <Command>
3    <Command.Panel>
4      <Command.Input placeholder="Search..." />
5      <Command.List>
6        <Command.Empty>No results found.</Command.Empty>
7        <Command.Item leadingIcon={<Calendar size={16} />}>
8          Calendar
9        </Command.Item>
10        <Command.Item leadingIcon={<Smile size={16} />}>
11          Search Emoji
12        </Command.Item>
13        <Command.Item leadingIcon={<Calculator size={16} />}>
14          Calculator
15        </Command.Item>

With Shortcuts and Footer

Annotate items with Command.Shortcut and pair with Command.Footer for help text.

1<Flex style={{ width: 420 }}>
2  <Command>
3    <Command.Panel>
4      <Command.Input placeholder="Search..." />
5      <Command.List>
6        <Command.Empty>No results found.</Command.Empty>
7        <Command.Item>
8          Profile <Command.Shortcut>⌘P</Command.Shortcut>
9        </Command.Item>
10        <Command.Item>
11          Billing <Command.Shortcut>⌘B</Command.Shortcut>
12        </Command.Item>
13        <Command.Item>
14          Settings <Command.Shortcut>⌘S</Command.Shortcut>
15        </Command.Item>

Command Dialog

Use Command.Dialog to render the command menu in a modal triggered by a keyboard shortcut.

1(function CommandDialogExample() {
2  const [open, setOpen] = React.useState(false);
3

4  React.useEffect(() => {
5    const handler = (event) => {
6      if ((event.metaKey || event.ctrlKey) && event.key === "k") {
7        event.preventDefault();
8        setOpen((prev) => !prev);
9      }
10    };
11    document.addEventListener("keydown", handler);
12    return () => document.removeEventListener("keydown", handler);
13  }, []);
14

15  return (

Controlled

Control the input value by passing value and onValueChange.

1(function ControlledCommand() {
2  const [value, setValue] = React.useState("");
3

4  return (
5    <Flex direction="column" gap="medium" style={{ width: 420 }}>
6      <Text>Query: {value || "(empty)"}</Text>
7      <Command value={value} onValueChange={setValue}>
8        <Command.Panel>
9          <Command.Input placeholder="Search..." />
10          <Command.List>
11            <Command.Empty>No results found.</Command.Empty>
12            <Command.Item>Calendar</Command.Item>
13            <Command.Item>Search Emoji</Command.Item>
14            <Command.Item>Calculator</Command.Item>
15          </Command.List>

Accessibility

  • Follows the WAI-ARIA Combobox pattern.
  • Input uses role="combobox", list uses role="listbox", items use role="option".
  • Keyboard: ArrowDown / ArrowUp move the highlight, Enter activates the highlighted item, Escape closes the dialog.
  • Disabled items expose aria-disabled="true" and are skipped in keyboard navigation.
  • When used inside Command.Dialog, focus is trapped in the dialog and returned to the trigger on close.