Um Guia Rápido para a API de Comandos Invoker

Se você já conectou um botão para abrir um elemento <dialog>, você conhece o processo: consultar o elemento, anexar um listener de clique, chamar showModal(). Funciona, mas é um código repetitivo que você escreve várias vezes. A API de Comandos Invoker muda isso ao permitir que você declare essa relação diretamente no HTML — sem JavaScript necessário para os casos mais comuns.

No final de 2025, a API de Comandos Invoker atingiu disponibilidade Baseline em Chrome/Edge, Firefox e Safari, tornando-a uma escolha prática para projetos modernos. Você pode verificar o suporte atual dos navegadores em webstatus.dev ou caniuse.com.

O Que São os Atributos command e commandfor?

A API de Comandos Invoker introduz dois atributos HTML em elementos <button>:

• commandfor — o id do elemento alvo que você deseja controlar
• command — a ação a ser executada nesse alvo quando o botão é ativado

Juntos, eles formam uma ligação declarativa entre um botão invocador e seu alvo. Quando o botão é clicado, pressionado via teclado ou ativado de outra forma, o navegador despacha um CommandEvent no elemento alvo e — para comandos integrados — executa o comportamento correspondente automaticamente.

Importante: Sempre adicione type="button" a qualquer botão usando esses atributos. Sem isso, botões dentro de formulários assumem o padrão type="submit", o que causa comportamento inesperado.

Controlando Diálogos e Popovers com HTML

É aqui que a API entrega o valor mais imediato. Anteriormente, controlar um elemento <dialog> exigia JavaScript. Agora você pode fazer isso de forma declarativa:

<button type="button" commandfor="my-dialog" command="show-modal">
  Abrir Diálogo
</button>

<dialog id="my-dialog">
  <p>Olá do diálogo!</p>
  <button type="button" commandfor="my-dialog" command="request-close">
    Fechar
  </button>
</dialog>

Sem JavaScript. O navegador lida com o posicionamento na camada superior, captura de foco e restauração do foco quando o diálogo fecha.

Referência de Comandos Integrados

Para popovers, isso serve a um propósito similar ao antigo atributo popovertarget. A API de Comandos Invoker é um mecanismo mais geral para ações declarativas de UI, mas os atributos originais de popover ainda existem e permanecem suportados. Veja o guia MDN para a API Popover para detalhes.

Acessibilidade Integrada

Para comandos integrados, o navegador lida automaticamente com os principais comportamentos de acessibilidade e interação. Os comandos de diálogo se integram ao tratamento nativo do <dialog> do navegador, incluindo comportamento de camada superior e restauração de foco quando o diálogo fecha. Esses comportamentos em nível de plataforma ajudam a garantir padrões de interação consistentes e melhor acessibilidade sem exigir atributos ARIA extras.

Comandos Personalizados Ainda Precisam de JavaScript

A API também suporta comandos personalizados para seus próprios componentes. Qualquer valor de command começando com -- é tratado como um comando personalizado. O navegador despacha um CommandEvent no alvo, e seu JavaScript cuida do resto:

<button type="button" commandfor="color-box" command="--toggle-highlight">
  Destacar
</button>
<div id="color-box"></div>

<script>
  document.getElementById('color-box').addEventListener('command', (e) => {
    if (e.command === '--toggle-highlight') {
      e.target.classList.toggle('highlighted');
    }
  });
</script>

O prefixo -- é um namespace reservado — os navegadores garantem que nunca o usarão para comandos integrados, então é seguro para uso personalizado. O CommandEvent expõe tanto e.command (a string do comando) quanto e.source (o botão que o disparou), fornecendo tudo o que você precisa para agir sobre o evento.

Conclusão

A API de Comandos Invoker torna o controle declarativo de UI em HTML uma realidade para os padrões mais comuns. Use comandos integrados para diálogos e popovers para obter acessibilidade, gerenciamento de foco e zero JavaScript gratuitamente. Use comandos personalizados -- quando precisar de comportamento JavaScript, mas quiser um padrão de conexão mais limpo e declarativo. É uma API pequena com escopo claro — e é exatamente isso que a torna útil.

Perguntas Frequentes

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.