CommandPalette
⌘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.
<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
groupvalue 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
#emptyslot. - 6.origam-command-palette__footer
- Footer bar with keyboard shortcut hints (
↑↓navigate,↵select,Escclose). Replaced by the#footerslot.
API
Props
Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et description.
- modelValueboolean
- v-model controlling whether the palette is open.
- hotkeyTCommandPaletteHotkey | 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.
- commandsReadonlyArray<ICommand>
- Static command list. When omitted the palette uses commands registered via the useCommand() global registry.
- filterTCommandPaletteFilter
- placeholderstring
- Placeholder text inside the search input (already-translated string).
- emptyTextstring
- Empty-state message displayed when no command matches the current query.
- maxHeightnumber | string
- Maximum height of the result list. Number is interpreted as px.
- widthnumber | string
- Width of the palette dialog. Number is interpreted as px.
- loadingbooleanfalse
- Displays a loader inside the result list while async commands are being fetched.
- searchIconTIcon
- loadingIconTIcon
- closeOnSelectbooleantrue
- Closes the palette automatically when a command is selected.
- closeOnEscapebooleantrue
- Closes the palette when the user presses Escape.
- closeOnBackdropbooleantrue
- Closes the palette when the user clicks the backdrop overlay.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- fontSizeTFontSize
- attachboolean | 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:modelValueboolean
- Fired when the open state changes (open/close).
- @selectICommand
- Fired when the user selects a command from the result list.
- @querystring
- 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
Interactions clavier
| Touche | Action |
|---|---|
| ↑ / ↓ | Move highlight between command items in the result list. |
| Enter | Execute the currently highlighted command. |
| Escape | Close the palette (when closeOnEscape=true). |
| ⌘K / Ctrl+K | Toggle 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.
- colorvar(--origam-color__surface---raised)
- Dialog panel background.
- dimensionvar(--origam-radius---lg)
- Dialog panel border-radius.
- shadowvar(--origam-shadow---xl)
- Dialog panel elevation shadow.
- colorvar(--origam-color__action--secondary---bg)
- Active item background.
- dimension640px
- Default dialog width.
- colorrgba(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
Async commands
Grouped commands