CommandPalette

Navigation
stable

⌘K-style command launcher overlay with fuzzy search, hotkey registration and a plugin registry via useCommand().

Structure

Anatomie

Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.

Anatomy of OrigamCommandPaletteSchematic of the CommandPalette component with numbered internal parts. 1 Type a command… 2 3 NAVIGATION 4 Go to Settings ⌘K 5 6 ① = backdrop (fixed / inset 0). ② = dialog (role="dialog"). ③ = group-title. ④ = item (role="option"). ⑤ = empty slot. ⑥ = footer.
Anatomy of <origam-command-palette> — 6 internal regions. The backdrop ① is a fixed scrim with blur; the dialog ② contains the search bar, listbox, and footer.
1.origam-command-palette__search
Search bar row. Contains a magnify icon and a <input role="combobox">.
2.origam-command-palette__dialog
Dialog panel (role="dialog" aria-modal="true"). Width controlled by --origam-command-palette---width.
3.origam-command-palette__group-title
Group subheader. Rendered for each distinct group value on commands.
4.origam-command-palette__item
Command row (role="option"). Active row receives the active background token. Hosts icon, label, description and kbd hint.
5.origam-command-palette__empty
Empty-state container. Rendered when no commands match. Replaced by the #empty slot.
6.origam-command-palette__footer
Footer bar with keyboard shortcut hints (↑↓ navigate, ↵ select, Esc close). Replaced by the #footer slot.

API

Props

Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et description.

modelValue
boolean
v-model controlling whether the palette is open.
hotkey
TCommandPaletteHotkey | null
[['meta', 'k'], ['ctrl', 'k']]
Global hotkey(s) that toggle the palette open. Defaults to ⌘K / Ctrl+K. Pass null to disable the global listener.
commands
ReadonlyArray<ICommand>
Static command list. When omitted the palette uses commands registered via the useCommand() global registry.
filter
TCommandPaletteFilter
placeholder
string
Placeholder text inside the search input (already-translated string).
emptyText
string
Empty-state message displayed when no command matches the current query.
maxHeight
number | string
Maximum height of the result list. Number is interpreted as px.
width
number | string
Width of the palette dialog. Number is interpreted as px.
loading
boolean
false
Displays a loader inside the result list while async commands are being fetched.
searchIcon
TIcon
loadingIcon
TIcon
closeOnSelect
boolean
true
Closes the palette automatically when a command is selected.
closeOnEscape
boolean
true
Closes the palette when the user presses Escape.
closeOnBackdrop
boolean
true
Closes the palette when the user clicks the backdrop overlay.
id
string
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue
fontSize
TFontSize
attach
boolean | string | Element | null

API

Slots

Emplacements de contenu exposés par ce composant.

#item
Custom renderer for each result row. Exposes the command data and whether it is currently highlighted.
#empty
Custom empty state shown when no commands match the query.
#search-icon
#loading
#footer
Optional footer rendered below the result list (e.g. keyboard shortcut hints).

API

Emits

Événements émis par ce composant.

@update:modelValue
boolean
Fired when the open state changes (open/close).
@select
ICommand
Fired when the user selects a command from the result list.
@query
string
Fired on every keystroke as the search query changes. Use for async command fetching.

API

Membres exposés

Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.

Ref<string>
Reactive current search query string.
ComputedRef<ICommand[]>
Computed list of commands that match the current query.
Ref<number>
Index of the currently highlighted command item in the filtered list.
Ref<boolean>
Whether the palette is currently open.

Personnalisation

Variables CSS

Propriétés CSS personnalisées exposées par ce composant. Surchargez-les pour personnaliser sans perdre la compatibilité avec le thème.

Stack order of the fixed backdrop.
Vertical offset from the top of the viewport to the dialog panel.
Width of the dialog panel. Clamped to calc(100vw - 32px) on small screens.
Dialog panel background color.
Dialog panel foreground color.
Dialog panel border-radius.
Box shadow on the dialog panel.
Semi-transparent backdrop color.
Backdrop blur applied to the fixed scrim.
Background of the currently highlighted command item.

Inclusion

Accessibilité

Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.

Rôles ARIA

dialog
combobox
listbox
option

Interactions clavier

Interactions clavier
ToucheAction
↑ / ↓Move highlight between command items in the result list.
EnterExecute the currently highlighted command.
EscapeClose the palette (when closeOnEscape=true).
⌘K / Ctrl+KToggle the palette open from anywhere in the page (global hotkey).

Notes

  • The search input uses role="combobox" with aria-controls pointing to the listbox, aria-expanded reflecting whether results are shown, and aria-activedescendant tracking the highlighted option.
  • The dialog panel uses role="dialog" aria-modal="true" and aria-labelledby pointing to the search input id. Focus is trapped inside while the palette is open.
  • Disabled commands have aria-disabled="true" and cannot be selected via keyboard or mouse.

Fondation

Design tokens

Extrait des tokens de ce composant — les variables --origam-<composant>---<propriété>, déclarées dans sa feuille de tokens tenue à la main, sans étape de build.

Source
color
var(--origam-color__surface---raised)
Dialog panel background.
dimension
var(--origam-radius---lg)
Dialog panel border-radius.
shadow
var(--origam-shadow---xl)
Dialog panel elevation shadow.
color
var(--origam-color__action--secondary---bg)
Active item background.
dimension
640px
Default dialog width.
color
rgba(0, 0, 0, 0.45)
Backdrop overlay color.

Interactif

Playground

Modifiez les props en direct et observez le composant se mettre à jour. Le snippet de code généré suit vos changements.

Rendu de l’aperçu en cours…

Usage

Exemples

Extraits de code prêts à coller dans vos templates.

Basic usage

vue

Async commands

vue

Grouped commands

vue