CommandPalette | Tuff Docs

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

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 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, Escape closes. The highlight starts on the first enabled command.
Keyboard selection is ignored during IME composition, so Chinese, Japanese, and Korean input is not submitted early.
The overlay is role="dialog" with aria-modal="true"; disabled commands carry aria-disabled="true" and never emit select.
The panel background is a card-preset TxBaseSurface (fake) under the search input, the list and the footer slot, refraction by default: a 50% base colour keeps text legible while the page behind still shows through to be blurred and refracted.
The overlay's dim is painted on a pseudo-element of the overlay rather than on its own background and opacity, so the panel's material samples the page, not only the dim.
The panel never fades as a whole as it opens and closes. Once its opacity animates, every backdrop filter inside it samples nothing but the panel, and the frost would drop out for the whole transition. What fades is each part of the panel instead: the content, the shadow and outline, and each layer of the material, so a material with a backdrop filter (such as the default refraction) 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