Command
newA filterable list of commands, inline or in a dialog, built on Reka UI's Listbox.
Open Props in the corner of the example to try size and disabled.
size takes Menu's scale: item heights from 28px at xs to 48px at xl, with the search row, icons and type to match.
Installation
Usage
<script setup lang="ts">
import {
Command,
CommandEmpty,
CommandGroup,
CommandInput,
CommandItem,
CommandLabel,
CommandList,
} from '@/components/ui/command'
</script>
<template>
<Command>
<CommandInput placeholder="Type a command or search..." />
<CommandList>
<CommandEmpty>No results found.</CommandEmpty>
<CommandGroup>
<CommandLabel>Suggestions</CommandLabel>
<CommandItem value="calendar" @select="openCalendar">Calendar</CommandItem>
</CommandGroup>
</CommandList>
</Command>
</template>
Command is a port of shadcn's command menu onto Reka UI's Listbox. Typing in CommandInput filters the items by their text, ignoring case and accents. A group with no match hides, separators hide while there is a search, and CommandEmpty shows when nothing matches. The arrow keys move the highlight from the search field, and Enter or a click fires the item's select and clears the search.
Command has no surface of its own beyond the popover colour and a radius, so give it a border or a shadow where it stands on the page. Items, labels, separators and shortcuts share Menu's styles.
Examples
Dialog
CommandDialog puts the command in a dialog, the usual command palette. It opens with v-model:open; here ⌘J or Ctrl+J also toggles it, since ⌘K already opens this site's search. The search takes focus when it opens. title and description name the dialog for screen readers only, and show-close-button adds the dialog's close button.
API Reference
Every part accepts class, merged over its base classes.
Command
| Prop | Default | Type and description |
|---|---|---|
| modelValue | "" | AcceptableValue | AcceptableValue[]The last selected item's value, bound with |
| defaultValue | — | AcceptableValue | AcceptableValue[]The starting value when |
| multiple | — | booleanLets several items be selected at once. |
| orientation | — | DataOrientationThe arrow keys' axis: |
| dir | — | DirectionThe reading direction. Defaults to the one Reka UI's |
| disabled | — | booleanDisables every item. |
| selectionBehavior | — | "toggle" | "replace"
|
| highlightOnHover | true | booleanMoves the highlight with the pointer. On by default. |
| loop | — | booleanWraps arrow-key navigation from the last item to the first and back. Needs |
| by | — | string | ((a: AcceptableValue, b: AcceptableValue) => boolean)A key or a function that compares item values, for object values. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| name | — | stringSubmits the selected value with the form under this name. |
| required | — | booleanMarks the selection required in a form. |
| size | "md" | MenuSizeMenu's scale, |
| ignoreFilter | false | booleanTurns the built-in filter off, for items you filter yourself. Every item, group and separator stays visible, and |
| Event | Payload and description |
|---|---|
| update:modelValue | [value: AcceptableValue]Fires when an item is selected. |
| highlight | [payload: { ref: HTMLElement; value: AcceptableValue; } | undefined]Fires when the highlight moves, with the item's value and element. |
| entryFocus | [event: CustomEvent<any>]Fires when focus enters the list. |
| leave | [event: Event]Fires when the pointer leaves the list. |
| Slot | Scope and description |
|---|---|
| default | {}The |
CommandDialog
| Prop | Default | Type and description |
|---|---|---|
| open | — | booleanWhether the dialog is open, bound with |
| defaultOpen | — | booleanOpens the dialog on mount when |
| modal | — | booleanBlocks the page behind the dialog. On by default. |
| unmountOnHide | — | booleanRemoves the window from the DOM while closed. Turn it off to keep its state between openings. |
| title | "Command Palette" | stringThe dialog's name for screen readers, "Command Palette" by default. |
| description | "Search for a command to run..." | stringThe dialog's description for screen readers, "Search for a command to run..." by default. |
| size | "md" | MenuSizeThe command's size, |
| ignoreFilter | false | booleanTurns the built-in filter off, for items you filter yourself. Every item, group and separator stays visible, and |
| showCloseButton | false | booleanAdds the dialog's close button. Off by default; Escape and a click outside close the dialog. |
| Event | Payload and description |
|---|---|
| update:open | [value: boolean]Fires when the dialog opens or closes. |
| Slot | Scope and description |
|---|---|
| default | { open: boolean; close: () => void; }The |
CommandInput
| Prop | Default | Type and description |
|---|---|---|
| modelValue | — | stringThe search text, bound with |
| autoFocus | — | booleanFocuses the search on mount. Off by default, since |
| disabled | — | booleanDisables the search field. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Event | Payload and description |
|---|---|
| update:modelValue | [value: string]Fires when the search text changes, also when selecting an item clears it. |
CommandItem
| Prop | Default | Type and description |
|---|---|---|
| value* | — | AcceptableValueThe item's value, emitted with |
| disabled | — | booleanKeeps the item visible but out of the highlight and selection. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Event | Payload and description |
|---|---|
| select | [event: SelectEvent$3<AcceptableValue>]Fires when the item is clicked or Enter is pressed on it. The search clears after it. |
| Slot | Scope and description |
|---|---|
| default | {}The item's icon, text and an optional |
CommandList
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}
|
CommandEmpty
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The text shown while a search matches nothing. |
CommandGroup
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}A |
CommandLabel
| Prop | Default | Type and description |
|---|---|---|
| for | — | stringSets the |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The group's name. |
CommandSeparator
| Prop | Default | Type and description |
|---|---|---|
| orientation | — | DataOrientationThe line's direction, |
| decorative | — | booleanHides the line from assistive technology. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
CommandShortcut
| Slot | Scope and description |
|---|---|
| default | {}The key combination, for display only. It does not register the shortcut. |
Props
- modelValue
"" AcceptableValue | AcceptableValue[]The last selected item's value, bound withv-model. Empty by default, so no item stays selected.- defaultValue
AcceptableValue | AcceptableValue[]The starting value whenv-modelis not used.- multiple
booleanLets several items be selected at once.- orientation
DataOrientationThe arrow keys' axis:vertical(the default) orhorizontal.- dir
DirectionThe reading direction. Defaults to the one Reka UI'sConfigProvidersets.- disabled
booleanDisables every item.- selectionBehavior
"toggle" | "replace"toggledeselects a selected item on a second select;replacekeeps it.- highlightOnHover
true booleanMoves the highlight with the pointer. On by default.- loop
booleanWraps arrow-key navigation from the last item to the first and back. Needsreka-ui2.11 or later.- by
string | ((a: AcceptableValue, b: AcceptableValue) => boolean)A key or a function that compares item values, for object values.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- name
stringSubmits the selected value with the form under this name.- required
booleanMarks the selection required in a form.- size
"md" MenuSizeMenu's scale,xstoxl: item heights from 28px to 48px, with the search row, icons and type to match.- ignoreFilter
false booleanTurns the built-in filter off, for items you filter yourself. Every item, group and separator stays visible, andCommandEmptynever shows.
Emits
- update:modelValue
[value: AcceptableValue]Fires when an item is selected.- highlight
[payload: { ref: HTMLElement; value: AcceptableValue; } | undefined]Fires when the highlight moves, with the item's value and element.- entryFocus
[event: CustomEvent<any>]Fires when focus enters the list.- leave
[event: Event]Fires when the pointer leaves the list.
Slots
- default
{}TheCommandInputand theCommandList.
Props
- open
booleanWhether the dialog is open, bound withv-model:open.- defaultOpen
booleanOpens the dialog on mount whenv-model:openis not used.- modal
booleanBlocks the page behind the dialog. On by default.- unmountOnHide
booleanRemoves the window from the DOM while closed. Turn it off to keep its state between openings.- title
"Command Palette" stringThe dialog's name for screen readers, "Command Palette" by default.- description
"Search for a command to run..." stringThe dialog's description for screen readers, "Search for a command to run..." by default.- size
"md" MenuSizeThe command's size,xstoxl.- ignoreFilter
false booleanTurns the built-in filter off, for items you filter yourself. Every item, group and separator stays visible, andCommandEmptynever shows.- showCloseButton
false booleanAdds the dialog's close button. Off by default; Escape and a click outside close the dialog.
Emits
- update:open
[value: boolean]Fires when the dialog opens or closes.
Slots
- default
{ open: boolean; close: () => void; }TheCommandInputand theCommandList, given the dialog'sclosefunction.
Props
- modelValue
stringThe search text, bound withv-model. Selecting an item clears it.- autoFocus
booleanFocuses the search on mount. Off by default, sinceCommandDialogfocuses it on open.- disabled
booleanDisables the search field.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Emits
- update:modelValue
[value: string]Fires when the search text changes, also when selecting an item clears it.
Props
- value*
AcceptableValueThe item's value, emitted withselectand stored inCommand'sv-model. The search matches the item's text.- disabled
booleanKeeps the item visible but out of the highlight and selection.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Emits
- select
[event: SelectEvent$3<AcceptableValue>]Fires when the item is clicked or Enter is pressed on it. The search clears after it.
Slots
- default
{}The item's icon, text and an optionalCommandShortcut.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}CommandEmpty, groups, items and separators.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The text shown while a search matches nothing.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}ACommandLabeland the group's items. The group hides while none of them matches.
Props
- for
stringSets theforattribute, for when the label renders as a<label>withas.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The group's name.
Props
- orientation
DataOrientationThe line's direction,horizontalby default.- decorative
booleanHides the line from assistive technology.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The key combination, for display only. It does not register the shortcut.
CommandGroup, CommandLabel, CommandList, CommandEmpty, CommandSeparator, CommandShortcut
CommandGroup holds a CommandLabel and items, CommandList scrolls them at up to 300px, and CommandShortcut shows a key combination at the end of an item without registering it.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| command | data-size | The root, Reka's Listbox root. |
| command-input-wrapper | The search row with its icon. | |
| command-input | The search field. | |
| command-list | The scrolling list, a role="listbox". | |
| command-empty | Shown while a search matches nothing. | |
| command-group | hidden | A role="group", hidden while none of its items matches. |
| command-label | The group's name. | |
| command-item | data-highlighted, data-disabled, data-state | One command, a role="option". |
| command-separator | A line between groups, removed while searching. | |
| command-shortcut | A key combination at the end of an item. |
Keyboard
| Key | Action |
|---|---|
| ArrowDown / ArrowUp | Moves the highlight to the next or previous enabled item. |
| Home / End | Moves the highlight to the first or last item. |
| Enter | Selects the highlighted item and clears the search. |
| Escape | Closes a CommandDialog. |