Components
CommandPalette
The root component. Renders a modal overlay with a search input, result list, and optional slots. Teleports to <body> by default.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
name | string | — | Target a specific named palette instance (default singleton when omitted) |
placeholder | string | 'Search commands…' | Input placeholder text |
maxResults | number | 10 | Maximum number of results shown |
emptyText | string | 'No commands found.' | Text shown when search returns nothing |
loadingText | string | 'Loading…' | Text shown while async groups are fetching |
teleportTo | string | 'body' | CSS selector for the <Teleport> target |
theme | 'default' | 'compact' | 'default' | Compact uses a narrower, shorter dialog |
animationDuration | number | 150 | Fade transition duration in ms |
labels | Partial<PaletteLabels> | — | Override built-in UI strings (i18n) — see Localization |
groupRecent | boolean | false | Cluster recent commands by their group with sub-headers |
modes | PaletteMode[] | — | Prefix-activated search scopes (see Modes / scopes) |
selectable | boolean | false | Multi-select mode (see Multi-select) |
preview | boolean | false | Show a preview pane for the active command (see Preview pane) |
previewHotkey | string[] | ['$mod', 'i'] | Key combo to toggle the preview pane ([] to disable) |
Emits
| Event | Payload | Description |
|---|---|---|
submit-selection | Command[] | Emitted on $mod+Enter in multi-select mode |
Slots
| Slot | Scope | Description |
|---|---|---|
#trigger | { open, toggle } | Custom element that opens the palette |
#header | — | Content inserted above the search input |
#input | { query, onInput } | Replace the default <input> entirely |
#item | { command, active, matches, parents, matchedText } | Replace the entire result row (parents = breadcrumb context; matchedText = matching keyword/alias) |
#group-header | { group } | Replace the group label row |
#empty | { query } | Shown when the query returns no results |
#actions | { command, run, activeIndex, close } | Replace the secondary-actions menu |
#preview | { command } | Preview pane content for the active command (requires preview prop) |
#footer | — | Content below the result list |
Custom #item slot
vue
<CommandPalette>
<template #item="{ command, active, matches }">
<div :class="['my-item', { 'my-item--active': active }]">
<span v-if="command.icon" class="my-item__icon">{{ command.icon }}</span>
<span class="my-item__body">
<component :is="highlightMatches(command.label, matches)" />
<span v-if="command.description" class="my-item__desc">
{{ command.description }}
</span>
</span>
<span v-if="command.shortcut?.length" class="my-item__shortcut">
<kbd v-for="k in command.shortcut" :key="k">{{ k }}</kbd>
</span>
<span v-if="command.subCommands?.length">›</span>
</div>
</template>
</CommandPalette>Custom #footer slot
vue
<CommandPalette>
<template #footer>
<div class="my-footer">
<span><kbd>↑↓</kbd> navigate</span>
<span><kbd>↵</kbd> select</span>
<span><kbd>Esc</kbd> close</span>
</div>
</template>
</CommandPalette>Programmatic trigger via #trigger slot
vue
<CommandPalette>
<template #trigger="{ toggle }">
<button @click="toggle">Open palette</button>
</template>
</CommandPalette>CommandItem
Renders a single command row with icon, label (with match highlighting), description, shortcut badge, loading spinner, and disabled state. Used internally; also available for custom layouts.
Props
| Prop | Type | Description |
|---|---|---|
command | Command | The command to render |
active | boolean | Whether this row is keyboard-selected |
matches | Array<[number, number]> | Highlight ranges from the fuzzy search engine |
itemId | string | id attribute for ARIA aria-activedescendant |
loadingCommandId | string | null | ID of the currently executing command; shows spinner |
Emits
| Event | Description |
|---|---|
execute | User clicked or pressed Enter on this item |
activate | User hovered over this item |
CommandGroup
Renders a group header followed by its CommandItem rows. Passes all #item, #item-icon, and #item-shortcut slots through to each child.
Props
| Prop | Type | Description |
|---|---|---|
group | CommandGroup | Group metadata (id, label, priority) |
items | SearchResult[] | Filtered results for this group |
activeIndex | number | Global active index for highlight tracking |
globalOffset | number | Index offset within the flat result list |
loadingCommandId | string | null | Forwarded to each CommandItem |