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

Lista de comandos inline

inline renderiza apenas o painel, então funciona em documentação e superfícies incorporadas sem overlay, portal, focus trap ou scroll lock. hint é texto secundário e também participa do filtro; shortcut apenas exibe teclas separadas por espaços.

esc

Dicas de teclado parciais

hints se mistura aos padrões, então mudar navigate e select preserva a dica de fechar. O emptyMessage padrão é seguido pela busca, então use uma abertura de frase como “No results for”.

esc

Trigger

Abrindo por um gatilho

CommandPalette.Trigger é uma propriedade estática do mesmo import. Passe o atalho que deseja exibir: ele nunca detecta Command versus Ctrl durante o render, pois isso causaria hydration mismatch.

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

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".
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.
O onSelect de um item roda antes do callback do palette. No modo modal, passe onClose para atualizar open; ao fechar, o foco volta ao elemento que abriu a paleta.
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

Nome	Tipo	Obrigatória	Descrição
`open`	`boolean`	—	Controls modal visibility. On close, the overlay and panel remain mounted for their exit motion. Ignored in inline mode.
`onClose`	`() => void`	—	Called when the palette is dismissed or an item is selected.
`onOpen`	`() => void`	—	Enables the global Command/Ctrl+hotkey listener and is called to open the palette.
`onSelect`	`(item: CommandItem) => void`	—	Called with the chosen item after its own `onSelect` callback.
`groups`	`CommandGroup[]`	—	Command groups to filter and render.
`placeholder`	`string`	—	Search field placeholder. Default: `"Type a command or search…"`.
`emptyMessage`	`string`	—	Text shown before the current query when no commands match. Default: `"No results for"`.
`searchLabel`	`string`	—	Accessible name for the command search field. Default: `"Search commands"`.
`hints`	`CommandPaletteHints`	—	Overrides for the footer keyboard hints. Merged over the defaults, so partial objects work.
`hotkey`	`string`	—	Key used with Command/Ctrl for the global shortcut. Default: `"k"`.
`inline`	`boolean`	—	Renders the panel without an overlay, portal, focus trap, or scroll lock.
`className`	`string`	—	Additional class name appended to `.lyra-cmdk`.
`'aria-label'`	`string`	—	Accessible name for the modal dialog. Default: `"Command palette"`. Translate it in a localized interface — it is what a screen reader announces when the palette opens. Ignored in inline mode, which is not a dialog.

x-data="lyraCommandPalette({ … })"

Opção	Tipo	Obrigatória	Descrição
`groups`	`LyraCommandPaletteGroup[]`	—	Command groups rendered through nested consumer `x-for` templates. Default: `[]`.
`open`	`boolean`	—	Overlay visibility; modelable with `x-modelable="open"`. Ignored in inline mode.
`placeholder`	`string`	—	Search input placeholder. Default: `"Type a command or search…"`.
`emptyMessage`	`string`	—	Text shown before a quoted unmatched query. Default: `"No results for"`.
`searchLabel`	`string`	—	Accessible search-input name. Default: `"Search commands"`.
`hints`	`LyraCommandPaletteHints`	—	Partial override for footer hint labels.
`hotkey`	`string \| false`	—	Command/Ctrl key used to toggle the overlay. Falsy disables it. Default: `"k"`.
`inline`	`boolean`	—	Render only the panel, without modal behavior. Default: `false`.
`label`	`string`	—	Accessible dialog name in overlay mode. Default: `"Command palette"`.

Esta é a estrutura de painel usada pelo modo inline. Um modal a envolve no overlay e adiciona a semântica de diálogo:

html

<div class="lyra-cmdk">
  <div class="lyra-cmdk__search">
    <input
      role="combobox"
      aria-label="Buscar comandos"
      aria-expanded="true"
      aria-controls="command-list"
      aria-autocomplete="list"
      aria-activedescendant="command-new-project"
    />
    <kbd class="lyra-kbd">esc</kbd>
  </div>
  <div class="lyra-cmdk__body" id="command-list" role="listbox">
    <div class="lyra-cmdk__group" role="group" aria-labelledby="create-label">
      <span class="lyra-cmdk__group-label" id="create-label">Criar</span>
      <button
        class="lyra-cmdk__item lyra-cmdk__item--active"
        id="command-new-project"
        type="button"
        role="option"
        aria-selected="true"
      >
        <span class="lyra-cmdk__item-label">Novo projeto</span>
        <span class="lyra-cmdk__shortcut"
          ><kbd class="lyra-kbd">C</kbd><kbd class="lyra-kbd">P</kbd></span
        >
      </button>
    </div>
  </div>
  <div class="lyra-cmdk__footer">
    <span><kbd class="lyra-kbd">↑</kbd><kbd class="lyra-kbd">↓</kbd> navegar</span>
  </div>
</div>

<lyra:command-palette> Gerado do lyra-ds/blade v0.10.0.

O comportamento vem de lyraCommandPalette() — instale @lyra-ds/alpine e veja a aba HTML + Alpine.

Prop	Padrão	Obrigatória	Valores de exemplo
`groups`	`[]`	—	—
`defaultOpen`	`false`	—	—
`placeholder`	`null`	—	—
`emptyMessage`	`null`	—	—
`searchLabel`	`null`	—	—
`hints`	`[]`	—	—
`hotkey`	`'k'`	—	—
`inline`	`false`	—	—
`label`	`null`	—	—

blade

<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'],
        ]],
    ]"
/>