Command Palette
Accessible controlled command dialog with grouped filtering, global invocation, complete keyboard navigation, and focus management.
- Selector
- ui-command-palette
- Package
- @ngnova/ui/command-palette
Import
import { UiCommandPaletteComponent } from '@ngnova/ui/command-palette';Usage & variants
Live examples use the public ui-command-palette API, paired with the exact snippet a product team would paste into an Angular app.
Project command search
Accessible controlled command dialog with grouped filtering, global invocation, complete keyboard navigation, and focus management.
Choose a project command.
Production guidance
Use these notes to decide when the component belongs in a product workflow and what to verify before shipping.
When to use
Use for expert-friendly navigation and actions spanning several application areas.
Watch for
Command values must be unique and stable because they drive active identity and DOM IDs.
Product recipes
Apply Command Palette in distinct, copyable product scenarios—not just an isolated component state.
Controlled workspace commands
The trigger, query, result, and business action remain explicit application state.
1 2 3 4 5 6 7 8 9 10 11 12 13
<button type="button" (click)="open.set(true)">
Search commands
</button>
<ui-command-palette
[commands]="commands"
[open]="open()"
(openChange)="open.set($event)"
[query]="query()"
(queryChange)="query.set($event)"
(commandSelected)="execute($event.command)"
ariaLabel="Workspace commands"
/>Navigation launcher
Group destinations by product area and let keyboard users move directly to a selected route.
1 2 3 4 5 6 7
<ui-command-palette
[open]="paletteOpen()"
[commands]="navigationCommands"
placeholder="Go to a page…"
(selected)="navigateTo($event)"
(openChange)="paletteOpen.set($event)"
/>API Reference
Inputs and outputs are semver-sensitive public API. Keep examples aligned with this table.
Inputs
commands [] readonly UiCommand[] Typed commands with stable values, searchable metadata, groups, and state.
open false boolean Controlled visibility state.
query '' string Controlled filter query.
disabled false boolean Prevents global keyboard invocation.
loading false boolean Announces and presents pending command loading.
shortcutEnabled true boolean Enables Ctrl/Cmd+K global invocation.
closeOnSelection true boolean Requests closure after an enabled command is selected.
closeOnBackdrop true boolean Requests closure after direct backdrop interaction.
closeOnEscape true boolean Requests closure after Escape while always emitting escapeKeyDown.
ariaLabel 'Command palette' string Accessible name for the modal dialog.
inputAriaLabel 'Search commands' string Accessible name for the filter combobox.
resultsAriaLabel 'Available commands' string Accessible name for command results.
placeholder 'Type a command or search...' string Localized filter placeholder.
emptyText 'No commands found.' string Localized empty-result message.
loadingText 'Loading commands...' string Localized loading message.
closeLabel 'Close command palette' string Accessible label for the close action.
hintText 'Use arrow keys to navigate and Enter to select' string Localized keyboard guidance.
shortcutHint 'Ctrl or Command + K' string Localized global shortcut hint.
| Name | Type | Default | Description |
|---|---|---|---|
commands | readonly UiCommand[] | [] | Typed commands with stable values, searchable metadata, groups, and state. |
open | boolean | false | Controlled visibility state. |
query | string | '' | Controlled filter query. |
disabled | boolean | false | Prevents global keyboard invocation. |
loading | boolean | false | Announces and presents pending command loading. |
shortcutEnabled | boolean | true | Enables Ctrl/Cmd+K global invocation. |
closeOnSelection | boolean | true | Requests closure after an enabled command is selected. |
closeOnBackdrop | boolean | true | Requests closure after direct backdrop interaction. |
closeOnEscape | boolean | true | Requests closure after Escape while always emitting escapeKeyDown. |
ariaLabel | string | 'Command palette' | Accessible name for the modal dialog. |
inputAriaLabel | string | 'Search commands' | Accessible name for the filter combobox. |
resultsAriaLabel | string | 'Available commands' | Accessible name for command results. |
placeholder | string | 'Type a command or search...' | Localized filter placeholder. |
emptyText | string | 'No commands found.' | Localized empty-result message. |
loadingText | string | 'Loading commands...' | Localized loading message. |
closeLabel | string | 'Close command palette' | Accessible label for the close action. |
hintText | string | 'Use arrow keys to navigate and Enter to select' | Localized keyboard guidance. |
shortcutHint | string | 'Ctrl or Command + K' | Localized global shortcut hint. |
Outputs
openChange OutputEmitterRef<boolean> Requests controlled visibility changes.
queryChange OutputEmitterRef<string> Requests controlled query changes.
commandSelected OutputEmitterRef<UiCommandSelection> Emits the selected command and keyboard or pointer source.
escapeKeyDown OutputEmitterRef<void> Emits every handled Escape key before dismissal policy.
| Name | Type | Description |
|---|---|---|
openChange | OutputEmitterRef<boolean> | Requests controlled visibility changes. |
queryChange | OutputEmitterRef<string> | Requests controlled query changes. |
commandSelected | OutputEmitterRef<UiCommandSelection> | Emits the selected command and keyboard or pointer source. |
escapeKeyDown | OutputEmitterRef<void> | Emits every handled Escape key before dismissal policy. |
Accessibility
- The open surface is an aria-modal dialog containing a named combobox and listbox with active-descendant wiring.
- Disabled commands remain discoverable but cannot become active or emit selection.
- Focus moves to search on open, stays trapped in the dialog, and returns to the previously focused control after controlled closure.
Keyboard behavior
- Ctrl+K or Command+K requests opening unless disabled or shortcutEnabled is false.
- Arrow Up/Down wraps through enabled results; Home/End moves to the first or last result.
- Enter selects the active command, Escape follows dismissal policy, and Tab remains inside the modal.
Testing guidance
- Assert global invocation, controlled query updates, grouped filtering, disabled commands, active wrapping, selection source, dismissal policy, focus trap/restore, localization, and UiCommandPaletteHarness behavior.