Overlays

CommandPalette

Modal search overlay for keyboard-first command launching and navigation. Filtering is consumer-owned: the `items` snippet receives `{ query }` and renders only the matching rows.

import { CommandPalette } from '@lostgradient/cinder/command-palette';
overlaycommand
01

Overview

Modal search overlay for keyboard-first commands, destinations, and record jumpers.

CommandPalette intentionally uses a native modal <dialog> for top-layer, backdrop, focus-trap, and aria-modal semantics. See the native dialog contract. For a non-modal single-value picker, use Combobox.

Usage

svelte 
<script lang="ts">
  import Button from '@lostgradient/cinder/button';
  import CommandItem from '@lostgradient/cinder/command-item';
  import CommandPalette from '@lostgradient/cinder/command-palette';

  let open = $state(false);
  let triggerRef: HTMLElement | null = $state(null);
  let lastSelected = $state('');

  const commands = [
    { value: 'new-file', label: 'New file' },
    { value: 'open-settings', label: 'Open settings' },
    { value: 'sign-out', label: 'Sign out' },
  ];

  function select(label: string) {
    lastSelected = label;
    open = false;
  }
</script>

<div style="display: flex; flex-direction: column; gap: 1rem; align-items: flex-start;">
  <Button
    label="Open palette"
    onclick={(event: MouseEvent) => {
      triggerRef = event.currentTarget as HTMLElement;
      open = true;
    }}
  />

  {#if lastSelected}
    <p style="font-size: 0.875rem; color: var(--cinder-text-muted);">
      Selected: <strong>{lastSelected}</strong>
    </p>
  {/if}
</div>

<CommandPalette bind:open label="Basic palette" {triggerRef}>
  {#snippet items({ query })}
    {@const filteredCommands = commands.filter((command) =>
      command.label.toLowerCase().includes(query.toLowerCase()),
    )}
    {#each filteredCommands as command (command.value)}
      <CommandItem
        value={command.value}
        accessibleLabel={command.label}
        onSelect={() => select(command.label)}
      >
        {command.label}
      </CommandItem>
    {/each}
  {/snippet}

  {#snippet empty()}
    No commands found.
  {/snippet}
</CommandPalette>

Grouped Results

Command items register with the palette by DOM node, so grouped results can use valid nested list markup without changing keyboard navigation. Use a presentational outer list item, an inner ul[role="group"] with an accessible name, and CommandItem children inside that inner list.

svelte 
<CommandPalette bind:open label="Command palette">
  {#snippet items()}
    <li role="presentation" class="cinder-command-group">
      <span class="cinder-command-group__label">Recent files</span>
      <ul role="group" aria-label="Recent files">
        <CommandItem value="roadmap" onSelect={() => openRoadmap()}>Roadmap</CommandItem>
        <CommandItem value="settings" onSelect={() => openSettings()}>Settings</CommandItem>
      </ul>
    </li>
  {/snippet}
</CommandPalette>
Live preview
02

When to use

Use when
  • Exposing a global keyboard-first launcher for power-user actions and navigation.
  • Letting users search across heterogeneous results such as commands, pages, and records in one input.
Avoid when
  • Picking a single value bound to a form field — use combobox instead.
  • Showing a contextual action menu attached to a trigger — use dropdown instead.
03

Examples

Basic command palette

A minimal palette with three items opened by a button.

Grouped command palette

Command items grouped with named listbox sections.

Search, recent, and keyed actions

Cmd+K opens the palette. Three sections: filtered search results, recent items, and keyed actions separated by visual group headers.

04

Props

Props for command-palette
NameTypeDefaultDescription
open bindable boolean false Bindable open state. The component mutates open = false on Escape, backdrop click, or any explicit close path, then fires onClose.
placeholder text 'Search…' Placeholder rendered inside the search input.
label text 'Command palette' Accessible name for the dialog, wired via aria-label.
query bindable text '' Bindable search query. Mutated by the input's oninput handler. Exposed to the items snippet so consumers can filter. Reset to an empty string each time the palette opens.
onClose () => void Fired after any close path routed through the palette close lifecycle.
triggerRef HTMLElement | null null Element to restore focus to on close. Falls back to captureFocus().
items required snippet Receives the current query so consumers can filter.
empty snippet Rendered when zero items are registered after filtering.
footer snippet Optional footer, e.g. for keybinding hints. Not part of the listbox.