Components

Command

A searchable palette under a scrim

Import

import { Command } from "@nyte-ai/ui/command";

A dialog near the top of the window holding an inline Autocomplete. The dialog owns open state, the scrim, and focus; the autocomplete owns the input, the highlight, and arrow-key and Enter handling. Focus lands in the input when the palette opens, and Enter runs the highlighted row's onClick.

Usage

The palette does not filter. Render the rows that match the query from onValueChange, and pass their values to items in render order, so the highlight tracks the rows that exist.
Command.Empty shows its children while items is empty and announces the change. Keep it mounted and change its text for loading, failure, and no match.
Command.Popup names the dialog with its title, read by screen readers only. Name the palette after what it searches.
Rows keep the menu's three columns, leading, label, and meta, so labels align in every group.
Coming from shadcn's Command: CommandDialog is Command.Root plus Command.Popup, heading keeps its name, onSelect is onClick, and CommandShortcut is meta. value on the popup is the query, as in Base UI, not the highlighted row. Use onItemHighlighted for that.

Anatomy

<Command.Root>
  <Command.Trigger />
  <Command.Popup>
    <Command.Input />
    <Command.List>
      <Command.Empty />
      <Command.Group>
        <Command.Item />
      </Command.Group>
      <Command.Separator />
    </Command.List>
  </Command.Popup>
</Command.Root>

Examples

const [open, setOpen] = useState(false);
const [query, setQuery] = useState("");
const matches = commands.filter((command) =>
  command.label.toLowerCase().includes(query.toLowerCase()),
);

<Command.Root open={open} onOpenChange={setOpen}>
  <Command.Trigger render={<Button variant="outline">Search</Button>} />
  <Command.Popup
    title="Search commands"
    items={matches.map((command) => command.id)}
    value={query}
    onValueChange={setQuery}
  >
    <Command.Input aria-label="Search" placeholder="Search…" trailing={<Kbd keys={["⌘", "K"]} />} />
    <Command.List>
      <Command.Empty>No commands match "{query}"</Command.Empty>
      <Command.Group heading="Commands">
        {matches.map((command) => (
          <Command.Item
            key={command.id}
            value={command.id}
            leading={<Icon name={command.icon} size={16} />}
            meta={<Kbd keys={command.keys} plain />}
            onClick={() => {
              setOpen(false);
              command.run();
            }}
          >
            {command.label}
          </Command.Item>
        ))}
      </Command.Group>
    </Command.List>
  </Command.Popup>
</Command.Root>;

Props

Part	Renders	Styling
`Command.Root`	Nothing	None
`Command.Trigger`	`<button>`	None
`Command.Popup`	A portal, the scrim, a viewport, a `<div>`, the list root	Translucent panel near the top
`Command.Input`	A `<div>` holding the search glyph and an `<input>`	Full-width row under a hairline
`Command.List`	`<div role="listbox">`	Scrolls when rows overflow
`Command.Group`	`<div role="group">` with an optional heading	Small, secondary heading
`Command.Separator`	`<div role="separator">`	Hairline
`Command.Item`	`<div role="option">`	Three columns, highlighted on hover
`Command.Empty`	`<div role="status">`	Centered secondary text
`Command.Close`	`<button>`	None

Except Command.Root, each part takes xstyle, className, and style. className and style take plain values, not functions of state. See Theming.

The part tables below come from Base UI, MIT, © Material-UI SAS.

Root

Groups all parts of the dialog. Doesn't render its own HTML element.

Root Props:

Prop	Type	Default	Description
defaultOpen	`boolean`	`false`	Whether the dialog is initially open. To render a controlled dialog, use the `open` prop instead.
open	`boolean`	-	Whether the dialog is currently open.
onOpenChange	`((open: boolean, eventDetails: Dialog.Root.ChangeEventDetails) => void)`	-	Event handler called when the dialog is opened or closed.
actionsRef	`React.RefObject<Dialog.Root.Actions \| null>`	-	A ref to imperative actions. `unmount`: Manually unmounts the dialog. Call this after any externally controlled closing animation finishes.`close`: Closes the dialog imperatively when called.
defaultTriggerId	`string \| null`	-	ID of the trigger that the dialog is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open dialog.
disablePointerDismissal	`boolean`	`false`	Whether to prevent the dialog from closing on outside presses. For non-modal dialogs, this also prevents the dialog from closing when focus moves outside of it.
handle	`Dialog.Handle<Payload>`	-	A handle to associate the dialog with a trigger. If specified, allows external triggers to control the dialog's open state. Can be created with the Dialog.createHandle() method.
modal	`boolean \| 'trap-focus'`	`true`	Determines if the dialog enters a modal state when open. `true`: user interaction is limited to just the dialog: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled.`false`: user interaction with the rest of the document is allowed.`'trap-focus'`: focus is trapped inside the dialog, but document page scroll is not locked and pointer interactions outside of it remain enabled. When `modal` is `true` or `'trap-focus'`, render `<Dialog.Close>` inside `<Dialog.Popup>` so touch screen readers can escape the popup.
onOpenChangeComplete	`((open: boolean) => void)`	-	Event handler called after any animations complete when the dialog is opened or closed.
triggerId	`string \| null`	-	ID of the trigger that the dialog is associated with. This is useful in conjunction with the `open` prop to create a controlled dialog. There's no need to specify this prop when the dialog is uncontrolled (that is, when the `open` prop is not set).
children	`React.ReactNode \| PayloadChildRenderFunction<Payload>`	-	The content of the dialog. This can be a regular React node or a render function that receives the `payload` of the active trigger.

Trigger

A button that opens the dialog. Renders a <button> element.

Trigger Props:

Prop	Type	Default	Description
handle	`Dialog.Handle<Payload>`	-	A handle to associate the trigger with a dialog. Can be created with the Dialog.createHandle() method.
nativeButton	`boolean`	`true`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).
payload	`Payload`	-	A payload to pass to the dialog when it is opened.
id	`string`	-	ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the dialog in controlled mode (with the Dialog.Root `triggerId` prop).
className	`string \| ((state: Dialog.Trigger.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Dialog.Trigger.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Dialog.Trigger.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Trigger Data Attributes:

Attribute	Type	Description
data-popup-open	-	Present when the corresponding dialog is open.
data-disabled	-	Present when the trigger is disabled.

Renders the portal, scrim, viewport, popup, and a visually hidden title, then an always-open inline autocomplete root with autoHighlight="always" and keepHighlight. It takes the Base UI dialog popup props, including ref, and these.

Prop	Type	Default	Description
`title`	`string`	`"Command palette"`	The dialog's accessible name.
`description`	`string`		The dialog's accessible description.
`tint`	`Tint`		Scopes the panel to a hue. The scrim stays neutral.
`items`	`readonly ItemValue[]`		Every row's `value`, in render order.
`loopFocus`	`boolean`	`true`	Whether arrow keys wrap from the last row to the first.
`value`	`string`		The controlled query.
`defaultValue`	`string`		The initial query when uncontrolled.
`onValueChange`	`(value, eventDetails) => void`		Fires as the query changes.
`onItemHighlighted`	`(value, eventDetails) => void`		Fires as the highlight moves.
`itemToStringValue`	`(value) => string`		Names a non-string `value` for assistive tech.

A container for the dialog contents. Renders a <div> element.

Popup Props:

Prop	Type	Default	Description
initialFocus	`boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| void \| HTMLElement \| null)`	-	Determines the element to focus when the dialog is opened. By default, focus moves to the first tabbable element inside the popup, except when the dialog is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard. `false`: Do not move focus.`true`: Move focus based on the default behavior (first tabbable element or popup).`RefObject`: Move focus to the ref element.`function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.
finalFocus	`boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)`	-	Determines the element to focus when the dialog is closed. `false`: Do not move focus.`true`: Move focus based on the default behavior (trigger or previously focused element).`RefObject`: Move focus to the ref element.`function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.
className	`string \| ((state: Dialog.Popup.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Dialog.Popup.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Dialog.Popup.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Popup Data Attributes:

Attribute	Type	Description
data-open	-	Present when the dialog is open.
data-closed	-	Present when the dialog is closed.
data-nested	-	Present when the dialog is nested within another dialog.
data-nested-dialog-open	-	Present when the dialog has other open dialogs nested within it.
data-starting-style	-	Present when the dialog begins animating in.
data-ending-style	-	Present when the dialog is animating out.

Popup CSS Variables:

Variable	Type	Description
`--nested-dialogs`	`number`	Indicates how many dialogs are nested within.

Input

Prop	Type	Default	Description
`trailing`	`ReactNode`		Right of the field: a shortcut, a clear button.

A text input to search for items in the list. Renders an <input> element.

Input Props:

Prop	Type	Default	Description
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
className	`string \| ((state: Autocomplete.Input.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Autocomplete.Input.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Autocomplete.Input.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Input Data Attributes:

Attribute	Type	Description
data-popup-open	-	Present when the corresponding popup is open.
data-popup-side	`'top' \| 'bottom' \| 'left' \| 'right' \| 'inline-end' \| 'inline-start' \| null`	Indicates which side the corresponding popup is positioned relative to its anchor.
data-list-empty	-	Present when the corresponding items list is empty.
data-pressed	-	Present when the input is pressed.
data-disabled	-	Present when the component is disabled.
data-readonly	-	Present when the component is readonly.
data-required	-	Present when the component is required.
data-valid	-	Present when the component is in a valid state (when wrapped in Field.Root).
data-invalid	-	Present when the component is in an invalid state (when wrapped in Field.Root).
data-dirty	-	Present when the component's value has changed (when wrapped in Field.Root).
data-touched	-	Present when the component has been touched (when wrapped in Field.Root).
data-filled	-	Present when the component has a value (when wrapped in Field.Root).
data-focused	-	Present when the input is focused (when wrapped in Field.Root).

List

A list container for the items. Renders a <div> element.

List Props:

Prop	Type	Default	Description
children	`React.ReactNode \| ((item: any, index: number) => React.ReactNode)`	-	-
className	`string \| ((state: Autocomplete.List.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Autocomplete.List.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Autocomplete.List.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Group

Prop	Type	Default	Description
`heading`	`ReactNode`		Labels the group; the rows follow.

Groups related items with the corresponding label. Renders a <div> element.

Group Props:

Prop	Type	Default	Description
items	`any[]`	-	Items to be rendered within this group. When provided, child `Collection` components will use these items.
className	`string \| ((state: Autocomplete.Group.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Autocomplete.Group.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Autocomplete.Group.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Group Data Attributes:

Attribute	Type	Description
data-popup-open	-	Present when the corresponding popup is open.
data-popup-side	`'top' \| 'bottom' \| 'left' \| 'right' \| 'inline-end' \| 'inline-start' \| null`	Indicates which side the corresponding popup is positioned relative to its anchor.
data-list-empty	-	Present when the corresponding items list is empty.
data-pressed	-	Present when the input group is pressed.
data-disabled	-	Present when the component is disabled.
data-readonly	-	Present when the component is readonly.
data-valid	-	Present when the component is in a valid state (when wrapped in Field.Root).
data-invalid	-	Present when the component is in an invalid state (when wrapped in Field.Root).
data-dirty	-	Present when the component's value has changed (when wrapped in Field.Root).
data-touched	-	Present when the component has been touched (when wrapped in Field.Root).
data-filled	-	Present when the component has a value (when wrapped in Field.Root).
data-focused	-	Present when the component is focused (when wrapped in Field.Root).

Separator

A visual separator between items or groups. Renders a <div> element.

Separator Props:

Prop	Type	Default	Description
orientation	`Orientation`	`'horizontal'`	The orientation of the separator.
className	`string \| ((state: Autocomplete.Separator.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Autocomplete.Separator.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Autocomplete.Separator.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Item

Prop	Type	Description
`value`	`ItemValue`	Identifies the row; it must appear in `items`.
`leading`	`ReactNode`	The glyph column.
`meta`	`ReactNode`	Display only. It binds no key.
`children`	`ReactNode`	The label.

An individual item in the list. Renders a <div> element.

Item Props:

Prop	Type	Default	Description
value	`any`	`null`	A unique value that identifies this item.
onClick	`((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void)`	-	An optional click handler for the item when selected. It fires when clicking the item with the pointer, as well as when pressing `Enter` with the keyboard if the item is highlighted when the `Input` or `List` element has focus.
index	`number`	-	The index of the item in the list. Improves performance when specified by avoiding the need to calculate the index automatically from the DOM.
nativeButton	`boolean`	`false`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
children	`React.ReactNode`	-	-
className	`string \| ((state: Autocomplete.Item.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Autocomplete.Item.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Autocomplete.Item.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Item Data Attributes:

Attribute	Type	Description
data-highlighted	-	Present when the item is highlighted.
data-disabled	-	Present when the item is disabled.

Empty

Renders its children only when the list is empty. Requires the items prop on the root component. Announces changes politely to screen readers. This component's root element must remain mounted in the DOM to announce changes consistently across screen readers. Avoid hiding or removing the component itself with display: none, hidden, aria-hidden, or conditional rendering. Prefer updating or conditionally rendering its children instead. Renders a <div> element.

Empty Props:

Prop	Type	Default	Description
className	`string \| ((state: Autocomplete.Empty.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Autocomplete.Empty.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Autocomplete.Empty.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Close

A button that closes the dialog. Renders a <button> element.

Close Props:

Prop	Type	Default	Description
nativeButton	`boolean`	`true`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).
className	`string \| ((state: Dialog.Close.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Dialog.Close.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Dialog.Close.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Close Data Attributes:

Attribute	Type	Description
data-disabled	-	Present when the button is disabled.