Skip to main content

Command

Filters a list of actions as the user types.

import { Command } from "@/fragments/ui";Source

Preview

<div style={{ maxWidth: '400px', width: '100%' }}>
  <Command>
    <Command.Input placeholder="Type a command..." />
    <Command.List>
      <Command.Item onItemSelect={() => {}}>Open File</Command.Item>
      <Command.Item onItemSelect={() => {}}>Save Document</Command.Item>

Installation

npx @usefragments/cli add command

Writes src/fragments/ui/components/Command plus what it imports, the globals stylesheet, and .fragments/registry-lock.json, then prints the packages to add. No account, no key.

Your own registry: publish from Fragments Cloud and add --registry org/name. Connect a workspace.

Anatomy

Command is a compound: import the root and reach its parts through dot notation.

  • Command.Input
  • Command.List
  • Command.Item
  • Command.Group
  • Command.Empty
  • Command.Separator

Search field over a flat list.

<div style={{ maxWidth: '400px', width: '100%' }}>
  <Command>
    <Command.Input placeholder="Type a command..." />
    <Command.List>
      <Command.Item onItemSelect={() => {}}>Open File</Command.Item>
      <Command.Item onItemSelect={() => {}}>Save Document</Command.Item>
      <Command.Item onItemSelect={() => {}}>Print</Command.Item>
      <Command.Empty>No results found.</Command.Empty>
    </Command.List>
  </Command>
</div>

Examples

Dialog Command Palette

The same list summoned over the page.

<Dialog>
  <Dialog.Trigger asChild>
    <Button variant="soft">Open Command Palette</Button>
  </Dialog.Trigger>
  <Dialog.Content width="sm">
    <Command>

With Groups

Category labels survive filtering.

<div style={{ maxWidth: '400px', width: '100%' }}>
  <Command>
    <Command.Input placeholder="Search..." />
    <Command.List>
      <Command.Group heading="Suggestions">
        <Command.Item onItemSelect={() => {}}>Calendar</Command.Item>

With Icons

Leading glyphs speed up scanning.

<div style={{ maxWidth: '400px', width: '100%' }}>
  <Command>
    <Command.Input placeholder="What do you need?" />
    <Command.List>
      <Command.Item onItemSelect={() => {}}>
        <span style={{ marginRight: '0.5rem', fontSize: '1rem' }}>+</span> New Document

API

Component props
Prop
Type
Default
Description
childrenRequirednodeNot setCommand.Input, Command.List, and other sub-components
searchstringNot setControlled search value
defaultSearchstringDefault search value (uncontrolled)
onSearchChangefunctionNot setCalled when search input changes
filterfunctionNot setCustom filter function. Return 0 to hide, >0 to show.
loopbooleantrueWhether to loop keyboard navigation
hostedbooleanfalseThe Command sits inside another surface (a Popover, a Dialog) that draws the frame, so it draws none of its own

Accessibility

  • Uses combobox + listbox ARIA pattern
  • Keyboard navigation with ArrowUp/ArrowDown, Enter to select
  • Home/End jump to first/last item
  • aria-activedescendant tracks focused item

Guidance

Use when

  • A keyboard shortcut that jumps anywhere
  • Action lists too long to scan
  • Inline lists that need filtering
  • Search across everything the app can do

Avoid when

  • A handful of actions (use Menu)
  • Picking a value for a form (use Select or Combobox)
  • Fixed navigation (use Sidebar or Tabs)

Related

  • DialogsiblingCompose inside Dialog for modal command palette
  • ListboxsiblingCommand uses Listbox-like keyboard navigation internally
  • ComboboxalternativeUse Combobox for form field selection with search

Next steps