elements
Manual UI Templates Command

Command

elements man ui/templates/command

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

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 (opens in a new tab): 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 (opens in a new tab): Pick one value, or several, from a styled listbox that lines the selected option up over the trigger.
  • Combobox (opens in a new tab): A text input that filters a list of options as you type, for one value or several shown as chips, with async results.