CommandPalette

CommandPalette é um índice buscável de comandos e destinos. Escolha entre abrir como modal global ou incorporar com inline; use Dropdown quando uma lista curta de comandos pertencer a um único controle.

Exemplos

Trigger

Return focus

In modal mode, use returnFocusTo for pointer-opened palettes. It is a synchronous resolver that runs once after an accepted close has committed, so it reads the current trigger and workflow state rather than a stale element. Keyboard opening can omit it when the captured opener remains a valid destination.

import { CommandPalette, type CommandGroup } from '@lyra-ds/react';
import { useRef, useState } from 'react';

function CommandPaletteExample({ canReturnToTrigger }: { canReturnToTrigger: boolean }) {
  const [open, setOpen] = useState(false);
  const [showTrigger, setShowTrigger] = useState(true);
  const triggerRef = useRef<HTMLButtonElement>(null);
  const successorRef = useRef<HTMLHeadingElement>(null);
  const groups: CommandGroup[] = [{ items: [{ id: 'projects', label: 'Projects' }] }];

  return (
    <>
      {showTrigger && (
        <CommandPalette.Trigger
          ref={triggerRef}
          label="Search commands"
          onClick={() => setOpen(true)}
        />
      )}
      <h2 ref={successorRef} tabIndex={-1}>
        Projects
      </h2>
      <CommandPalette
        open={open}
        onClose={() => {
          setShowTrigger(false);
          setOpen(false);
        }}
        returnFocusTo={() =>
          canReturnToTrigger && triggerRef.current ? triggerRef.current : successorRef.current
        }
        groups={groups}
      />
    </>
  );
}

The returned element must be connected, visible, enabled, in the same document, and programmatically focusable. A named region with tabIndex={-1} is a valid successor when the trigger is removed or no longer meaningful; a removed trigger's null ref falls back to that successor even if availability has not changed. Hidden, inert, and aria-hidden ancestors make a target ineligible, as do the closing panel, overlay, and their descendants while exit presence keeps them mounted. Invalid results fall back to a valid captured opener. If neither target is eligible, Lyra makes no invalid focus call and emits a development diagnostic once for that close cycle. After removal the browser may leave focus on body. That is an invalid invoking composition, not a successful restoration. returnFocusTo is ignored by inline, and it never runs for ignored close requests or closed renders. Omitted pointer-opened consumers are not automatically repaired.

Initial focus

initialFocusTo is optional and has the type () => HTMLElement | null. In modal mode, Lyra calls this synchronous, read-only resolver once for each accepted opening. Normal command interaction omits it, so the eligible search field remains the task-control default. When an application intentionally needs a declared destination, it can return the current named palette panel, which is already present with tabIndex={-1}. A null or invalid result focuses that panel directly; it never falls through to another control. Inline palettes ignore initialFocusTo.

An eligible target is an HTMLElement in the panel's document and current modal panel, connected, visible with rendered rectangles, enabled (including its fieldset), programmatically focusable, and outside hidden, inert, or aria-hidden ancestry. The resolver is not replayed on rerenders; a later accepted opening reads the current resolver. Form composition owns focus after failed validation, so initial entry never infers failure from aria-invalid.

The resolver only reads committed state and refs: do not focus, mutate, or start asynchronous work. If it throws, Lyra focuses the panel and propagates the same error; the palette's animation-frame context reports it through normal browser error handling, not a React error boundary.

Quando usar

Use CommandPalette quando as pessoas precisarem de um índice buscável de ações ou destinos, acessível pelo teclado.

Prefira outro componente quando:

• Poucos comandos pertencem a um controle visível — use Dropdown.
• A escolha muda o workspace ativo — use WorkspaceSwitcher, que informa a seleção.
• A pessoa alterna entre poucas visualizações pares — use Tabs.

Acessibilidade

• In inline and modal mode, the actual search input and command items have a 44px minimum target in both dimensions for fine, coarse and hybrid pointers, without brand configuration. Their minimum height uses max(44px, var(--control-md)); set the existing --control-md sizing token on the palette or an ancestor (for example, --control-md: 56px) to raise it. Smaller values keep the 44px floor.
• O campo de busca é um role="combobox" com aria-expanded, aria-controls, aria-autocomplete="list" e aria-activedescendant. Os resultados são role="option" dentro de um role="listbox"; grupos rotulados usam role="group".
• Durante a busca normal, o foco DOM fica no campo. As setas movem o foco virtual pelas opções, permitindo continuar digitando enquanto o descendente ativo muda; Enter seleciona o item ativo e Escape chama onClose. Um destino declarado no painel da paleta também é suportado.
• O onSelect de um item roda antes do callback do palette. No modo modal, passe onClose para atualizar open; use returnFocusTo quando uma paleta aberta por ponteiro precisar de um destino explícito.
• O modo modal faz portal de um role="dialog" nomeado, prende o foco, bloqueia a rolagem e permanece montado durante a animação de saída. Passe aria-label para substituir “Command palette” numa interface localizada. O modo inline não é diálogo e não tem nome de diálogo.
• O campo de busca de comandos tem o nome "Search commands" por padrão. Passe searchLabel para traduzi-lo.
• onOpen instala o listener global Command/Ctrl+hotkey (k por padrão). Ele fica de propósito fora destes exemplos porque este site de documentação já é dono desse atalho.
• Abaixo de 720px, Trigger se reduz ao ícone enquanto o rótulo visível e o atalho ficam ocultos. Ele preserva o nome acessível de label; o ícone de busca é decorativo, então esse rótulo deve ser significativo.

API e código

<div
  x-data="lyraCommandPalette({
    groups: [],
    hotkey: false,
    label: 'Search commands',
    searchLabel: 'Search commands',
    returnFocusTo: () => {
      const trigger = document.getElementById('open-command-palette');
      return trigger instanceof HTMLButtonElement && !trigger.disabled && !trigger.hidden
        ? trigger
        : document.getElementById('command-workflow');
    },
  })"
>
  <button
    id="open-command-palette"
    class="lyra-cmdk-trigger"
    type="button"
    aria-label="Search commands"
    @click="open = true"
  >
    Search commands
  </button>
  <h2 id="command-workflow" tabindex="-1">Command workflow</h2>

  <div class="lyra-cmdk-overlay" x-bind="overlay" style="display: none">
    <div class="lyra-cmdk" x-bind="panel">
      <div class="lyra-cmdk__search">
        <input x-bind="search" />
        <kbd class="lyra-kbd">esc</kbd>
      </div>
      <div class="lyra-cmdk__body" x-bind="list">
        <p class="lyra-cmdk__empty" x-bind="empty" x-text="emptyText()"></p>
      </div>
      <div class="lyra-cmdk__footer">
        <button class="lyra-btn lyra-btn--ghost lyra-btn--md" type="button" @click="open = false">
          Close
        </button>
      </div>
    </div>
  </div>
</div>

<lyra:command-palette
    placeholder="Type a command or search…"
    empty-message="No results found."
    hotkey="k"
    :groups="[
        ['label' => 'Navigation', 'items' => [
            ['id' => 'go-projects', 'label' => 'Go to projects'],
            ['id' => 'go-billing', 'label' => 'Go to billing'],
        ]],
        ['label' => 'Actions', 'items' => [
            ['id' => 'new-project', 'label' => 'Create a project'],
        ]],
    ]"
/>