# Command

A searchable, ranked list of actions run from the keyboard: inline, in a popover, or as a command palette.

```ehtml Example
import {
  Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator,
  CommandShortcut, CommandDialog,
} from "@elements/ui/command";
import { Icon } from "@elements/ui/icon";

<Command>
  <CommandInput placeholder="Type a command or search..." />
  <CommandList>
    <CommandEmpty>No results found.</CommandEmpty>
    <CommandGroup heading="Suggestions">
      <CommandItem onSelect={() => go("/calendar")}><Icon name="calendar" /> Calendar</CommandItem>
      <CommandItem><Icon name="search" /> Search Emoji</CommandItem>
    </CommandGroup>
    <CommandSeparator />
    <CommandGroup heading="Settings">
      <CommandItem>Profile <CommandShortcut>⌘P</CommandShortcut></CommandItem>
    </CommandGroup>
  </CommandList>
</Command>

<!-- a palette on Cmd+K -->
<CommandDialog open={state.palette} shortcut="k">...same parts...</CommandDialog>
```

## Parts

| Part | What it is |
|---|---|
| `Command` | The root: filters, ranks and highlights its items, and owns the keyboard. |
| `CommandInput` | The search input (role=combobox). Focus stays here; arrows move the highlight. |
| `CommandList` | The listbox. It scrolls past a height and exposes --command-list-height for a height transition. |
| `CommandEmpty` | Shown only when no item matches. |
| `CommandLoading` | A progress row for async items. |
| `CommandGroup` | A titled group. Hidden when none of its items match; ranked by its best match. |
| `CommandItem` | An action. value (or its text) and keywords are what the search matches; onSelect runs on click or Enter. |
| `CommandSeparator` | A line between groups; hidden while searching unless alwaysRender. |
| `CommandShortcut` | A key hint at the end of an item. |
| `CommandDialog` | Command in a modal Dialog, with an optional Cmd/Ctrl shortcut that toggles it. |

## Attributes

### Command

| Attribute | Type | Default | Description |
|---|---|---|---|
| `value` | `string` (two-way) | `""` | The highlighted item's value. Bind it to read or move the highlight. |
| `search` | `string` (two-way) | `""` | The search text. Bind it to read or set the query. |
| `label` | `string` | `"Command menu"` | Accessible name for the menu. |
| `filter` | `((value: string, search: string, keywords: string[]) => number) \| null` | `commandScore` | Ranks an item from 0 (hidden) to 1. null turns filtering and ranking off: render the results yourself, as for async or virtual lists. |
| `loop` | `boolean` | `false` | Arrow keys wrap from the last item to the first. |
| `vimBindings` | `boolean` | `true` | Ctrl+N and Ctrl+J move down, Ctrl+P and Ctrl+K move up. |
| `disablePointerSelection` | `boolean` | `false` | The mouse does not move the highlight. |
| `bordered` | `boolean` | `false` | Draw the overlay border and shadow, for a Command placed in the page. |
| `class` | `string` | `""` | Extra classes on the root; on CommandDialog, on the dialog content. |
| `onValueChange` | `(value: string) => void` | `() => {}` | The highlight moved. |
| `onSearchChange` | `(search: string) => void` | `() => {}` | The user typed. |
| `onKeyDown` | `(e: KeyboardEvent) => void` | `() => {}` | Every key on the root before Command handles it. e.preventDefault() takes the key (nested pages). |

### CommandInput

| Attribute | Type | Default | Description |
|---|---|---|---|
| `placeholder` | `string` | `"Type a command or search..."` | Input placeholder. |
| `disabled` | `boolean` | `false` | Disables the input. |
| `attrs` | `Record<string, ...>` | `{}` | Spread onto the input. |

### CommandList

| Attribute | Type | Default | Description |
|---|---|---|---|
| `label` | `string` | `"Suggestions"` | The listbox's accessible name. |

### CommandLoading

| Attribute | Type | Default | Description |
|---|---|---|---|
| `progress` | `number` | `-1` | 0 to 100 for determinate progress; -1 for none. |
| `label` | `string` | `"Loading..."` | Text and accessible name. |

### CommandGroup

| Attribute | Type | Default | Description |
|---|---|---|---|
| `heading` | `string` | `""` | The group's title, which names the group. |
| `value` | `string` | `its heading` | The group's data-value; give one when there is no heading. |

### CommandGroup, CommandItem

| Attribute | Type | Default | Description |
|---|---|---|---|
| `forceMount` | `boolean` | `false` | Show it whatever the search. |

### CommandItem

| Attribute | Type | Default | Description |
|---|---|---|---|
| `value` | `string` | `its text` | What the search matches and what onSelect and the root's value get. |
| `keywords` | `string[]` | `[]` | Aliases the search also matches. |
| `disabled` | `boolean` | `false` | Shown, skipped, does not run. |
| `onSelect` | `(value: string) => void` | `() => {}` | Runs on click or Enter. |

### CommandSeparator

| Attribute | Type | Default | Description |
|---|---|---|---|
| `alwaysRender` | `boolean` | `false` | Keep it while searching. |

### CommandDialog

| Attribute | Type | Default | Description |
|---|---|---|---|
| `open` | `boolean` (two-way) | `false` | Whether the palette is open. |
| `title, description` | `string` | `"Command Palette", "Search for a command to run..."` | The dialog's accessible name and description (visually hidden). |
| `showCloseButton` | `boolean` | `true` | Show the dialog's close button, at the end of the search row. |
| `shortcut` | `string` | `""` | A key that, with Cmd or Ctrl, toggles the palette from anywhere ("k"). |
| `value, search, label, filter, loop, vimBindings, disablePointerSelection, onValueChange, onSearchChange, onKeyDown` | `as on Command` | `as on Command` | Passed to the Command inside. |
| `onOpenChange` | `(open: boolean) => void` | `() => {}` | The palette opened or closed itself. |

## Slots

| Slot | Part | Content |
|---|---|---|
| `default` |  | CommandInput and CommandList. |
| `default` | `CommandList` | Items, groups, separators, CommandEmpty and CommandLoading. |
| `default` | `CommandItem` | Icon, label, CommandShortcut. |
| `trigger` | `CommandDialog` | An element that opens the palette. |

## Keyboard

| Keys | Action |
|---|---|
| `Typing` | Filters and ranks; the best match is highlighted. |
| `ArrowDown / ArrowUp` | Next or previous item; wraps with loop. |
| `Ctrl + N / J, Ctrl + P / K` | Next and previous (vimBindings). |
| `Alt + ArrowDown / ArrowUp` | First item of the next or previous group; with no group that way, the next or previous item. |
| `Meta + ArrowDown / ArrowUp` | Last or first item. |
| `Home / End` | First or last item, also from the input. |
| `Enter` | Runs the highlighted item. |
| `Cmd / Ctrl + shortcut` | CommandDialog: toggles the palette. |
| `Escape` | Inline: clears a typed search. CommandDialog: closes and returns focus. |
| `Escape / Backspace on an empty search` | Pages demo: back a page, through onKeyDown. |

## Data attributes

| Attribute | Values | On | Description |
|---|---|---|---|
| `data-highlighted` | present | .command-item | The keyboard or mouse highlight. |
| `data-selected` | present | .command-item | Another name for the same highlight, set with data-highlighted, so styles written for either name apply. |
| `data-disabled` | present | .command-item |  |
| `data-value` | string | .command-item, .command-group | The item's value (given, or its text, trimmed); the group's value or heading. |
| `hidden` | present | .command-item, .command-group, .command-separator, .command-empty | Filtered out. |
| `data-empty` | present | .command | Nothing matches. |
| `--command-list-height` | px | .command-list | Height of the list's content, for height: var(--command-list-height) with a transition. |
| `--command-max-height` | length | .command-list | Set it to change where the list starts scrolling. |

## Accessibility

- The input is a combobox named by label (aria-labelledby), with aria-autocomplete=list, aria-expanded=true) controlling the listbox; aria-activedescendant names the highlighted item.
- Items are options; the highlighted one has aria-selected=true. Disabled items have aria-disabled.
- While ranked, aria-posinset and aria-setsize give each item its place in the order shown.
- Groups are role=group named by their heading.
- CommandDialog is a modal Dialog named by its title and described by its description, both visually hidden.
- Focus stays in the input while the mouse presses items.

## See also

- [Icon](icon): An inline stroke icon from the set the templates draw their own controls with, sized in pixels and colored by the text around it.
- [Select](select): Pick one value, or several, from a styled listbox that lines the selected option up over the trigger.
- [Combobox](combobox): A text input that filters a list of options as you type, for one value or several shown as chips, with async results.