Command Palette

Spotlight-style command palette with search and keyboard shortcuts.

Components

Command Palette

feedback

interactive

<arc-command-palette>

Overview

CommandPalette provides a spotlight-style overlay for quick access to application commands, navigation, and actions. It renders as a centered modal dialog with a prominent 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 from a clean state 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, preventing the background page from shifting 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 designed 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 animated scale-in transition on open
Auto-focusing search input that resets the query on every open
Live type-ahead filtering against command item labels
Full 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

Open CommandPalette

New File

Open File

Save

Toggle Dark Mode

Go to Settings

Sign Out

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

open boolean =false: 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.
placeholder string ='Type a command...': Placeholder text displayed in the search input when the query is empty.
max-results number =50: 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.

Events

arc-select detail: { value: string, item: { label: string, shortcut: string, value: string } }: Fired when a command item is selected. `detail.value` is the item's `value`, falling back to its label.
arc-close: Fired when the palette closes

CommandItem

<arc-command-item>

Action item inside a CommandPalette.

label
selectionValue: What arc-select reports. Falls back to the label so an item that never sets `value` behaves as it always did.
shortcut string ='': Keyboard shortcut hint
icon string ='': Name of the icon to display before the item label.
keywords string ='': Extra space-separated terms the search filter matches against but never displays — e.g. keywords="dialog popup" on a Modal item.
description string ='': 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.
value string ='': 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.

heading string ='': Heading text displayed above the group’s items.

Command Palette

Overview

Guidelines

When to use

When not to use

Features

Preview

Usage

API

Events

CommandItem

CommandGroup

See Also

Docs

Project

Arclight