CommandPalette
An overlay for searching and running commands.
Usage
Launcher
Loading demo...
Best Practices
- Keep
idstable across releases, and use it — not the localized title — for analytics, persistence, and permission checks. - Put synonyms, aliases, and plugin names in
keywordsinstead of duplicating commands for search variants. - Register global shortcuts in the app shell, then open the palette through
v-model. - Use
footerfor sources, result counts, or keyboard help; useemptyto show the query and a recovery action. - Cap
maxHeightfor long command sets so the palette stays inside the viewport.
API Reference
Props
| Name | Type | Default | Description |
|---|---|---|---|
modelValue | boolean | - | Whether the palette is shown, bound with v-model. |
commands | CommandPaletteItem[] | [] | The commands. |
placeholder | string | 'Search commands' | Search placeholder; also the input's aria-label. |
emptyText | string | 'No commands found' | Text shown when nothing matches. |
maxHeight | number | 320 | Maximum list height in px. |
autoFocus | boolean | true | Focuses the search input on open. |
closeOnSelect | boolean | true | Closes after a selection; set false for batch actions. |
overlayClass | string | string[] | Record<string, boolean> | - | Class for the overlay. |
panelClass | string | string[] | Record<string, boolean> | - | Class for the panel. |
query | string | - | Search text for v-model:query; omit to let the palette manage it. |
ariaLabel | string | 'Command palette' | Accessible name of the dialog and command list. |
surface | 'pure' | 'mask' | 'blur' | 'glass' | 'refraction' | 'acrylic' | 'mica' | 'flat' | 'plain' | 'refraction' | Material of the panel. |
surfaceColor | string | '' | Colour laid under the material; follows the theme by default. |
surfaceOpacity | number | 0.96 for mask, 0.5 otherwise | Opacity of that colour, used by mask, blur, acrylic, glass and refraction; always opaque under pure and flat, and mica and plain lay no base colour. |
Events
| Event | Payload | Description |
|---|---|---|
update:modelValue | (value) | Fires when the palette asks to open or close. |
select | (item) | Fires with the original item when an enabled command is chosen. |
open | - | Fires when the palette opens. |
close | - | Fires when an open palette closes. |
update:query | (value) | Fires on input; resets to an empty string on close. |
Slots
| Slot | Props | Description |
|---|---|---|
empty | { query, emptyText } | Content shown when nothing matches. |
footer | { query, visibleCount } | Area below the list. |
Types
CommandPaletteItem
| Field | Type | Description |
|---|---|---|
id | string | Unique id. |
title | string | Title; searched. |
description | string | Line under the title; searched. |
keywords | string[] | Extra search terms; not displayed. |
icon | TxIconSource | string | Icon source or icon class. |
shortcut | string | Shortcut hint on the right; registers nothing. |
disabled | boolean | Stays visible but can't be selected. |
Overview
- Visibility comes only from
modelValue. The palette emitsopenwhen shown andclosewhen an open palette is dismissed. - Filtering is a local, case-insensitive substring match over
title,description, andkeywords; there is no ranking, debouncing, or remote fetch.ArrowDown/ArrowUpcycle and skip disabled commands,Enterselects, and the highlight starts on the first enabled command. Keyboard selection is ignored during IME composition. - The overlay is
role="dialog"witharia-modal="true"; disabled commands carryaria-disabled="true"and never emitselect. - Tab and Shift+Tab cycle inside the panel, stopping only at controls that show and are in the tab order, while commands move with
↑/↓. With focus outside the panel, Tab comes in at the first control and Shift+Tab at the last.Escapecloses the palette whether or not focus is in it; both rules hold only while the palette is topmost. - Closing returns focus to where it was before the palette opened, without scrolling the page. For the 340 ms it fades out, the overlay is
inert, so the pointer and focus reach the layer below. - The panel background is a card-preset
TxBaseSurface(fake),refractionby default, and the overlay's dim is painted on a pseudo-element, so the material samples the page. The panel fades part by part rather than as a whole, so a material with a backdrop filter samples the page from the first frame to the last.
Technologies
- The outline and shadow are painted on the panel's
::after; apanelClassthat changes them restyles that layer, and a different base colour goes throughsurfaceColorrather than a background on the panel itself. - Source:
packages/tuffex/packages/components/src/command-palette/.
查看源码
packages/tuffex/packages/components/src/command-palette/index.ts