Command Palette
Spotlight-style command palette with search and keyboard shortcuts.
<arc-command-palette>Overview
CommandPalette is a spotlight-style overlay for quick access to application commands, navigation, and actions. It renders as a centered modal dialog with a search input at the top, a scrollable results list in the middle, and a keyboard-hint footer at the bottom. Users open it with a trigger (typically a keyboard shortcut like Cmd+K), type to filter commands, and press Enter to execute the focused item.
The palette accepts <arc-command-item> children in its default slot, each with a label and an optional shortcut string. On open, the search input auto-focuses and the query resets so users start clean every time. The filtered results update live as the user types, matching against each item's label. Arrow keys cycle the focus highlight through the visible results, and the footer displays the key bindings so users can navigate without a mouse.
When an item is selected (by clicking or pressing Enter), the palette dispatches an arc-select event containing the item's label and shortcut, then closes itself. The Escape key and backdrop click both dismiss the palette and fire an arc-close event. The component locks body scroll while open and restores it on close, so the background page does not shift under the overlay.
Guidelines
When to use
- Bind a global keyboard shortcut (e.g. Cmd+K) to toggle the open property for fast access
- Provide concise, action-oriented labels on each <arc-command-item> (e.g. "Open File", "Toggle Theme")
- Include shortcut hints on items that have associated keyboard bindings for discoverability
- Close the palette programmatically after handling the arc-select event to confirm the action ran
- Keep the command list under 20-30 items; for larger sets, rely on the search filter
When not to use
- Do not use CommandPalette as a generic search bar; it is for discrete actions, not content search
- Do not leave the palette open after an item is selected; it should always close to return focus to the app
- Do not put nested interactive components like forms or modals inside command items
- Do not omit the label attribute on <arc-command-item>; the filter and display both depend on it
- Do not override the body scroll lock behavior, as this prevents jarring background movement
Features
- Centered modal dialog with a scale-in transition on open
- Auto-focusing search input that resets the query on every open
- Live type-ahead filtering against command item labels
- Keyboard navigation: ArrowUp/ArrowDown cycle focus, Enter selects, Escape closes
- Keyboard shortcut hints displayed next to each command item in monospace
- Footer bar showing navigation key bindings for discoverability
- Backdrop overlay with click-to-close and body scroll locking
- `arc-select` and `arc-close` custom events for integration with application logic
Preview
Usage
This component requires JavaScript. No pure HTML/CSS version is available. Use the Web Component directly or a framework wrapper.
<arc-button onclick="document.querySelector('#palette').open = true">Open Palette</arc-button>
<arc-command-palette id="palette">
<arc-command-item shortcut="⌘O">Open File</arc-command-item>
<arc-command-item shortcut="⌘S">Save File</arc-command-item>
</arc-command-palette>import { Button, CommandItem, CommandPalette } from '@arclux/arc-ui-react';
export default function Example() {
return (
<>
<Button onclick="document.querySelector('#palette').open = true">Open Palette</Button>
<CommandPalette id="palette">
<CommandItem shortcut="⌘O">Open File</CommandItem>
<CommandItem shortcut="⌘S">Save File</CommandItem>
</CommandPalette>
</>
);
}<script setup>
import { Button, CommandItem, CommandPalette } from '@arclux/arc-ui-vue';
</script>
<template>
<Button onclick="document.querySelector('#palette').open = true">Open Palette</Button>
<CommandPalette id="palette">
<CommandItem shortcut="⌘O">Open File</CommandItem>
<CommandItem shortcut="⌘S">Save File</CommandItem>
</CommandPalette>
</template><script>
import { Button, CommandItem, CommandPalette } from '@arclux/arc-ui-svelte';
</script>
<Button onclick="document.querySelector('#palette').open = true">Open Palette</Button>
<CommandPalette id="palette">
<CommandItem shortcut="⌘O">Open File</CommandItem>
<CommandItem shortcut="⌘S">Save File</CommandItem>
</CommandPalette>import { Component } from '@angular/core';
import { Button, CommandItem, CommandPalette } from '@arclux/arc-ui-angular';
@Component({
imports: [Button, CommandItem, CommandPalette],
template: `
<arc-button onclick="document.querySelector('#palette').open = true">Open Palette</arc-button>
<arc-command-palette id="palette">
<arc-command-item shortcut="⌘O">Open File</arc-command-item>
<arc-command-item shortcut="⌘S">Save File</arc-command-item>
</arc-command-palette>
`,
})
export class MyComponent {}import { Button, CommandItem, CommandPalette } from '@arclux/arc-ui-solid';
export default function Example() {
return (
<>
<Button onclick="document.querySelector('#palette').open = true">Open Palette</Button>
<CommandPalette id="palette">
<CommandItem shortcut="⌘O">Open File</CommandItem>
<CommandItem shortcut="⌘S">Save File</CommandItem>
</CommandPalette>
</>
);
}import { Button, CommandItem, CommandPalette } from '@arclux/arc-ui-preact';
export default function Example() {
return (
<>
<Button onclick="document.querySelector('#palette').open = true">Open Palette</Button>
<CommandPalette id="palette">
<CommandItem shortcut="⌘O">Open File</CommandItem>
<CommandItem shortcut="⌘S">Save File</CommandItem>
</CommandPalette>
</>
);
}API
placeholderstring'Type a command...'- Placeholder text displayed in the search input when the query is empty.
max-resultsnumber50- How many ranked results to render. Truncation happens after ranking, so what survives is the best of the set. Raise it for a short command list; the default suits a large one.
openbooleanfalse- Controls whether the palette is visible. When set to true, the dialog animates in, the search input auto-focuses, and body scroll is locked. Set to false to close.
Events
arc-selectdetail:{ value: string, item: { label: string, shortcut: string, value: string } }- Fired when a command item is selected.
detail.valueis the item'svalue, falling back to its label. arc-close- Fired when the palette closes
CommandItem
<arc-command-item>Action item inside a CommandPalette.
labelselectionValue- What arc-select reports. Falls back to the label so an item that never sets
valuebehaves as it always did. shortcutstring''- Keyboard shortcut hint
iconstring''- Name of the icon to display before the item label.
keywordsstring''- Extra space-separated terms the search filter matches against but never displays, e.g. keywords="dialog popup" on a Modal item.
descriptionstring''- Secondary line shown under the label and matched by search. Use it for the sentence that tells two similar results apart; a docs site can put the matching passage here so a query finds page content rather than only page titles.
valuestring''- Stable identifier carried on the arc-select detail. Defaults to the label, which is fine until two items share one; give anything a handler must act on its own value rather than matching against display text.
CommandGroup
<arc-command-group>Groups CommandItems under a small uppercase heading in the results list. Items inside a group still filter and keyboard-navigate as one flat list; headings disappear when none of their items match.
headingstring''- Heading text displayed above the group’s items.