Command

Fast, composable command menu built on top of the Base UI Autocomplete primitive.
1(function CommandDialogExample() {
2  const [open, setOpen] = React.useState(false);
3

4  return (
5    <Command.Dialog open={open} onOpenChange={setOpen}>
6      <Command.DialogTrigger render={<Button variant="outline" />}>
7        Open Command Menu
8      </Command.DialogTrigger>
9      <Command.DialogContent>
10        <Command>
11          <Command.Input placeholder="Search..." />
12          <Command.Content>
13            <Command.Empty>No results found.</Command.Empty>
14            <Command.Group>
15              <Command.Label>Actions</Command.Label>

Anatomy

Import and assemble the component inside Command.Dialog for a command palette:

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

3<Command.Dialog>
4  <Command.DialogTrigger>Open</Command.DialogTrigger>
5  <Command.DialogContent>
6    <Command>
7      <Command.Input />
8      <Command.Content>
9        <Command.Empty>No results found.</Command.Empty>
10        <Command.Group>
11          <Command.Label>Suggestions</Command.Label>
12          <Command.Item>Item</Command.Item>
13        </Command.Group>
14        <Command.Separator />
15      </Command.Content>
16    </Command>
17  </Command.DialogContent>
18</Command.Dialog>

Command can also be rendered inline (without a dialog) — useful for embedding a persistent command menu in a page or surface.

API Reference

Root

The root element owns the input value, the list of items, and the context used by every sub-component. Renders as a styled panel that gives the command menu its popover look.

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

Content

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 inside Command.Content.

Prop

Type

Label

Renders a label inside Command.Group. The label is hidden automatically while the user is searching.

Prop

Type

Separator

Visual divider between groups. The separator is hidden automatically while the user is searching.

Prop

Type

Shortcut

A <kbd> element for keyboard hints. Typically passed as trailingIcon on Command.Item.

Prop

Type

Dialog

Command.Dialog is an alias for the Base UI Dialog root. Pair it with Command.DialogTrigger and Command.DialogContent to render the command menu in a centered modal.

Prop

Type

DialogContent

Renders the portal, backdrop, viewport, and popup for the command palette. The backdrop is not blurred by default — pass overlay={{ blur: true }} to enable it. Unlike Dialog.Content, there is no close button; users dismiss the palette via Escape or by clicking the backdrop.

Prop

Type

Examples

Inline

A command menu rendered inline, without a dialog. Use this when the command menu is a permanent surface on the page.

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

Groups and Separators

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

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

4  return (
5    <Command.Dialog open={open} onOpenChange={setOpen}>
6      <Command.DialogTrigger render={<Button variant="outline" />}>
7        Open Command Menu
8      </Command.DialogTrigger>
9      <Command.DialogContent>
10        <Command>
11          <Command.Input placeholder="Type a command or search..." />
12          <Command.Content>
13            <Command.Empty>No results found.</Command.Empty>
14            <Command.Group>
15              <Command.Label>Suggestions</Command.Label>

With Icons

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

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

4  return (
5    <Command.Dialog open={open} onOpenChange={setOpen}>
6      <Command.DialogTrigger render={<Button variant="outline" />}>
7        Open Command Menu
8      </Command.DialogTrigger>
9      <Command.DialogContent>
10        <Command>
11          <Command.Input placeholder="Search..." />
12          <Command.Content>
13            <Command.Empty>No results found.</Command.Empty>
14            <Command.Item leadingIcon={<Home />} onClick={() => setOpen(false)}>
15              Home

Keyboard Shortcut

Bind a keyboard shortcut (e.g. ⌘K) to toggle the command palette open.

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        event.stopPropagation();
9        event.stopImmediatePropagation();
10        setOpen((prev) => !prev);
11      }
12    };
13    document.addEventListener("keydown", handler, true);
14    return () => document.removeEventListener("keydown", handler, true);
15  }, []);

Controlled

Control the input value by passing value and onValueChange.

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

5  return (
6    <Command.Dialog open={open} onOpenChange={setOpen}>
7      <Command.DialogTrigger render={<Button variant="outline" />}>
8        Open Command Menu
9      </Command.DialogTrigger>
10      <Command.DialogContent>
11        <Command value={value} onValueChange={setValue}>
12          <Command.Input placeholder="Search..." />
13          <Command.Content>
14            <Command.Empty>No results found.</Command.Empty>
15            <Command.Item onClick={() => setOpen(false)}>Calendar</Command.Item>

Items prop

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). Command.Content then accepts a render function that receives each item.

1(function ItemsCommand() {
2  const [open, setOpen] = React.useState(false);
3  const items = [
4    "Calendar",
5    "Search Emoji",
6    "Calculator",
7    "Profile",
8    "Billing",
9    "Settings",
10  ];
11

12  return (
13    <Command.Dialog open={open} onOpenChange={setOpen}>
14      <Command.DialogTrigger render={<Button variant="outline" />}>
15        Open Command Menu

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.