Guide rapide de l'API Invoker Commands

Si vous avez déjà connecté un bouton pour ouvrir un élément <dialog>, vous connaissez la procédure : interroger l’élément, attacher un écouteur de clic, appeler showModal(). Cela fonctionne, mais c’est du code répétitif que vous écrivez encore et encore. L’API Invoker Commands change la donne en vous permettant de déclarer cette relation directement dans le HTML — sans JavaScript pour les cas les plus courants.

Fin 2025, l’API Invoker Commands a atteint la disponibilité Baseline sur Chrome/Edge, Firefox et Safari, ce qui en fait un choix pratique pour les projets modernes. Vous pouvez vérifier la compatibilité navigateur actuelle sur webstatus.dev ou caniuse.com.

Que sont les attributs command et commandfor ?

L’API Invoker Commands introduit deux attributs HTML sur les éléments <button> :

• commandfor — l’id de l’élément cible que vous souhaitez contrôler
• command — l’action à effectuer sur cette cible lorsque le bouton est activé

Ensemble, ils forment un lien déclaratif entre un bouton invocateur et sa cible. Lorsque le bouton est cliqué, pressé via le clavier ou activé d’une autre manière, le navigateur envoie un CommandEvent sur l’élément cible et — pour les commandes intégrées — exécute automatiquement le comportement correspondant.

Important : Ajoutez toujours type="button" à tout bouton utilisant ces attributs. Sans cela, les boutons à l’intérieur de formulaires ont par défaut type="submit", ce qui provoque un comportement inattendu.

Contrôler les dialogues et popovers avec HTML

C’est là que l’API apporte la valeur la plus immédiate. Auparavant, contrôler un élément <dialog> nécessitait du JavaScript. Maintenant, vous pouvez le faire de manière déclarative :

<button type="button" commandfor="my-dialog" command="show-modal">
  Open Dialog
</button>

<dialog id="my-dialog">
  <p>Hello from the dialog!</p>
  <button type="button" commandfor="my-dialog" command="request-close">
    Close
  </button>
</dialog>

Aucun JavaScript. Le navigateur gère le placement en couche supérieure, le piégeage du focus et la restauration du focus lorsque le dialogue se ferme.

Référence des commandes intégrées

Pour les popovers, cela remplit un objectif similaire à l’ancien attribut popovertarget. L’API Invoker Commands est un mécanisme plus général pour les actions d’interface déclaratives, mais les attributs popover d’origine existent toujours et restent pris en charge. Consultez le guide MDN de l’API Popover pour plus de détails.

L’accessibilité est intégrée

Pour les commandes intégrées, le navigateur gère automatiquement les comportements clés d’accessibilité et d’interaction. Les commandes de dialogue s’intègrent à la gestion native <dialog> du navigateur, y compris le comportement de couche supérieure et la restauration du focus lorsque le dialogue se ferme. Ces comportements au niveau de la plateforme contribuent à garantir des modèles d’interaction cohérents et une meilleure accessibilité sans nécessiter d’attributs ARIA supplémentaires.

Les commandes personnalisées nécessitent toujours du JavaScript

L’API prend également en charge les commandes personnalisées pour vos propres composants. Toute valeur command commençant par -- est traitée comme une commande personnalisée. Le navigateur envoie un CommandEvent sur la cible, et votre JavaScript gère le reste :

<button type="button" commandfor="color-box" command="--toggle-highlight">
  Highlight
</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>

Le préfixe -- est un espace de noms réservé — les navigateurs garantissent qu’ils ne l’utiliseront jamais pour les commandes intégrées, il est donc sûr pour un usage personnalisé. Le CommandEvent expose à la fois e.command (la chaîne de commande) et e.source (le bouton qui l’a déclenché), vous donnant tout ce dont vous avez besoin pour agir sur l’événement.

Conclusion

L’API Invoker Commands rend le contrôle déclaratif de l’interface utilisateur en HTML une réalité pour les modèles les plus courants. Utilisez les commandes intégrées pour les dialogues et popovers afin d’obtenir gratuitement l’accessibilité, la gestion du focus et zéro JavaScript. Utilisez les commandes personnalisées -- lorsque vous avez besoin d’un comportement JavaScript mais souhaitez un modèle de connexion plus propre et plus déclaratif. C’est une petite API avec une portée claire — et c’est exactement ce qui la rend utile.

FAQ

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.