Components/CommandPalette

CommandPalette

An overlay for searching and running commands.

VerifiedSince 0.3.4

Usage

Launcher

Loading demo...

Best Practices

  • Keep id stable across releases, and use it — not the localized title — for analytics, persistence, and permission checks.
  • Put synonyms, aliases, and plugin names in keywords instead of duplicating commands for search variants.
  • Register global shortcuts in the app shell, then open the palette through v-model.
  • Use footer for sources, result counts, or keyboard help; use empty to show the query and a recovery action.
  • Cap maxHeight for long command sets so the palette stays inside the viewport.

API Reference

Props

NameTypeDefaultDescription
modelValueboolean-Whether the palette is shown, bound with v-model.
commandsCommandPaletteItem[][]The commands.
placeholderstring'Search commands'Search placeholder; also the input's aria-label.
emptyTextstring'No commands found'Text shown when nothing matches.
maxHeightnumber320Maximum list height in px.
autoFocusbooleantrueFocuses the search input on open.
closeOnSelectbooleantrueCloses after a selection; set false for batch actions.
overlayClassstring | string[] | Record<string, boolean>-Class for the overlay.
panelClassstring | string[] | Record<string, boolean>-Class for the panel.
querystring-Search text for v-model:query; omit to let the palette manage it.
ariaLabelstring'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.
surfaceColorstring''Colour laid under the material; follows the theme by default.
surfaceOpacitynumber0.96 for mask, 0.5 otherwiseOpacity 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

EventPayloadDescription
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

SlotPropsDescription
empty{ query, emptyText }Content shown when nothing matches.
footer{ query, visibleCount }Area below the list.

Types

CommandPaletteItem

FieldTypeDescription
idstringUnique id.
titlestringTitle; searched.
descriptionstringLine under the title; searched.
keywordsstring[]Extra search terms; not displayed.
iconTxIconSource | stringIcon source or icon class.
shortcutstringShortcut hint on the right; registers nothing.
disabledbooleanStays visible but can't be selected.

Overview

  • Visibility comes only from modelValue. The palette emits open when shown and close when an open palette is dismissed.
  • Filtering is a local, case-insensitive substring match over title, description, and keywords; there is no ranking, debouncing, or remote fetch. ArrowDown / ArrowUp cycle and skip disabled commands, Enter selects, and the highlight starts on the first enabled command. Keyboard selection is ignored during IME composition.
  • The overlay is role="dialog" with aria-modal="true"; disabled commands carry aria-disabled="true" and never emit select.
  • 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. Escape closes 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), refraction by 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; a panelClass that changes them restyles that layer, and a different base colour goes through surfaceColor rather than a background on the panel itself.
  • Source: packages/tuffex/packages/components/src/command-palette/.
查看源码
packages/tuffex/packages/components/src/command-palette/index.ts