CommandBox

InstallationCopy Anchor Link

npx vayu-ui-cli@latest add command-box

UsageCopy Anchor Link

AnatomyCopy Anchor Link

import { CommandBox } from 'vayu-ui';

<CommandBox open={open} onOpenChange={setOpen}>
  <CommandBox.Overlay>
    <CommandBox.Input placeholder="Search..." />
    <CommandBox.List>
      <CommandBox.Group label="Section">
        <CommandBox.Item id="item-1" shortcut={['⌘', 'N']} icon={<Icon />}>
          Item Label
        </CommandBox.Item>
      </CommandBox.Group>
      <CommandBox.Separator />
      <CommandBox.Empty>No results found.</CommandBox.Empty>
    </CommandBox.List>
  </CommandBox.Overlay>
</CommandBox>;

• CommandBox — Root container. Manages open/close state, search filtering, and keyboard navigation.
• CommandBox.Overlay — Portal-based overlay with backdrop. Renders the command box centered on screen.
• CommandBox.Input — Search input with combobox ARIA role. Handles arrow key navigation and Enter selection.
• CommandBox.List — Scrollable listbox container for items and groups.
• CommandBox.Group — Groups items under a sticky label header.
• CommandBox.Item — Individual option with support for icons, descriptions, keyboard shortcuts, and disabled state.
• CommandBox.Separator — Visual divider between groups.
• CommandBox.Empty — No-results message shown when search yields no matches.

AccessibilityCopy Anchor Link

• Keyboard Support:
  • ArrowDown — Move highlight to the next item.
  • ArrowUp — Move highlight to the previous item.
  • Enter — Select the highlighted item and close the palette.
  • Home — Jump highlight to the first item.
  • End — Jump highlight to the last item.
  • Escape — Close the palette.
  • Modifier shortcuts (e.g., ⌘+N, Ctrl+K) — Select the matching item directly.
• ARIA Attributes:
  • Input has role="combobox" with aria-expanded, aria-controls, and aria-activedescendant.
  • List has role="listbox" linked via aria-controls.
  • Each item has role="option" with aria-selected and aria-disabled.
  • Groups use role="group" with aria-label.
  • Separator uses role="separator" with aria-orientation="horizontal".
  • Empty state uses role="status" with aria-live="polite".
  • Backdrop is marked aria-hidden="true".
• Focus Behavior:
  • Input auto-focuses when the palette opens.
  • Highlighted item scrolls into view automatically.
  • Body scroll is locked while the palette is open.

Screen reader behaviorCopy Anchor Link

When the command palette opens, the screen reader announces the search input as a combobox. As the user types, filtered results update in the live region. The highlighted item is announced via aria-activedescendant on the input. Each option is announced with its role ("option") and selected state. Group labels are announced when navigating into a new group via aria-label on the group container. The empty state message is announced through the aria-live="polite" region when no results match. When the palette closes, focus returns to the previously focused element.

Component Folder StructureCopy Anchor Link

CommandBox/
├── CommandBox.tsx            # Root component with state management and filtering
├── CommandBoxInput.tsx       # Search input with combobox ARIA role
├── CommandBoxList.tsx        # Scrollable listbox container
├── CommandBoxItem.tsx        # Self-registering option with selection states
├── CommandBoxGroup.tsx       # Grouped items with sticky label header
├── CommandBoxSeparator.tsx   # Visual divider between groups
├── CommandBoxEmpty.tsx       # No-results state with aria-live
├── CommandBoxOverlay.tsx     # Portal-based overlay with backdrop
├── hooks.ts                  # Context provider and fuzzy search utility
├── types.ts                  # TypeScript type definitions
└── index.ts                  # Re-exports all components and types

PropsCopy Anchor Link

CommandBox (Root)Copy Anchor Link

CommandBox.InputCopy Anchor Link

CommandBox.ListCopy Anchor Link

CommandBox.ItemCopy Anchor Link

CommandBox.GroupCopy Anchor Link

CommandBox.EmptyCopy Anchor Link

CommandBox.SeparatorCopy Anchor Link

CommandBox.OverlayCopy Anchor Link