Modern Web Guidance

Overview

Use the Invoker Commands API to toggle the visibility of <dialog> and [popover] elements directly from HTML buttons, eliminating the need for custom JavaScript event listeners.

By applying the commandfor (target ID) and command (action) attributes to a <button>, the browser automatically handles open/close state changes, focus management, and accessibility bindings (such as aria-expanded). This declarative approach is recommended because it removes brittle boilerplate code, ensures interactions are functional immediately upon HTML parsing, and guarantees a robust, natively accessible user experience.

Implementing Declarative Popovers

Popovers can be toggled open and closed using a single button.

<!-- MANDATORY: The commandfor attribute links the invoker to the ID of the target element so the browser knows what to control. -->
<!-- MANDATORY: The command attribute specifies the action to perform. Use 'toggle-popover' to handle both open and close states automatically. -->
<button commandfor="my-popover" command="toggle-popover">
  Toggle Popover
</button>

<!-- MANDATORY: The target element must have the popover attribute to be controlled as a popover. -->
<div id="my-popover" popover>
  <p>Popover content goes here.</p>
</div>

If you need to control opening and closing with separate buttons, you can use the show-popover and hide-popover commands.

<!-- MANDATORY: Use 'show-popover' to explicitly open the popover. It will not close the popover if clicked again. -->
<button commandfor="my-explicit-popover" command="show-popover">
  Show Popover
</button>

<div id="my-explicit-popover" popover="manual">
  <p>This popover is explicitly opened and closed by separate buttons.</p>

  <!-- MANDATORY: Use 'hide-popover' to explicitly close the targeted popover. -->
  <button commandfor="my-explicit-popover" command="hide-popover">
    Hide Popover
  </button>
</div>

Implementing Declarative Modal Dialogs

Unlike popovers, modal dialogs typically use separate buttons for opening and closing. Use the show-modal command specifically when you need to open a dialog as a modal.

<!-- MANDATORY: Use command="show-modal" to trigger the dialog as a modal, trapping focus and preventing interaction with the rest of the page. -->
<!-- MANDATORY: The commandfor attribute connects this button to the dialog ID. -->
<button commandfor="confirm-dialog" command="show-modal">
  Open Confirmation
</button>

<dialog id="confirm-dialog">
  <p>Are you sure you want to proceed?</p>

  <!-- MANDATORY: Use command="close" to dismiss the dialog safely. -->
  <button commandfor="confirm-dialog" command="close">
    Cancel
  </button>
</dialog>

Fallback strategies

Baseline status for Invoker commands: Newly available. It's been Baseline since 2025-12-12. Supported by: Chrome 135 (Apr 2025), Edge 135 (Apr 2025), Firefox 144 (Oct 2025), and Safari 26.2 (Dec 2025). Baseline status for Popover: Newly available. It's been Baseline since 2025-01-27. Supported by: Chrome 116 (Aug 2023), Edge 116 (Aug 2023), Firefox 125 (Apr 2024), Safari 17 (Sep 2023), and Safari iOS 18.3 (Jan 2025).

Because Invoker Commands and Popovers are not yet universally supported, you MUST use polyfills as fallbacks for older browsers.

Polyfilling Invoker Commands

MANDATORY: Feature detect support by checking for the commandForElement property on the HTMLButtonElement prototype. Do NOT check the window or document object. You MUST dynamically import the polyfill only when the native feature is missing. DO NOT unconditionally load the polyfill. Mandatory: Listen for the 'command' event directly on the target element because the native 'command' event does not bubble.

Option 1: Using a bundler Install the polyfill via npm (npm install invokers-polyfill). This approach is for projects using a bundler (like Vite or Webpack) or import maps. For all other setups, use the CDN option below.

// MANDATORY: Feature detect 'commandForElement' on HTMLButtonElement.prototype.
// Conditionally load the invokers-polyfill only in browsers lacking native support.
if (!('commandForElement' in HTMLButtonElement.prototype)) {
  import('invokers-polyfill');
}

Option 2: Using a CDN For projects without a bundler, dynamically import the polyfill directly from a CDN inside a <script type="module">.

<script type="module">
  // MANDATORY: Feature detect 'commandForElement' on HTMLButtonElement.prototype.
  // Conditionally load the invokers-polyfill from a CDN only in browsers lacking native support.
  if (!('commandForElement' in HTMLButtonElement.prototype)) {
    import('https://esm.run/invokers-polyfill');
  }
</script>

Invokers Polyfill Limitations MANDATORY: This polyfill does not handle the ARIA states (e.g., aria-expanded) of the command button the way native browsers do. You are strongly encouraged to handle these states yourself to ensure your site is fully accessible.

Baseline status for Invoker commands: Newly available. It's been Baseline since 2025-12-12. Supported by: Chrome 135 (Apr 2025), Edge 135 (Apr 2025), Firefox 144 (Oct 2025), and Safari 26.2 (Dec 2025).

If the Invoker Commands API is not supported, the command event will not fire. For full support across all modern browsers, it is recommended to use the invokers-polyfill from https://github.com/keithamus/invokers-polyfill via npm install or CDN.

This polyfill fully supports custom actions (starting with --) and dispatches the command event exactly like the native API.

Dynamic Import (Performance Optimization)

For the best performance, you should only load the polyfill if the browser doesn't support the API natively. This saves bandwidth and reduces script execution time for users on modern browsers.

// Check for native support first
const hasNativeSupport = 'commandForElement' in HTMLButtonElement.prototype;

if (!hasNativeSupport) {
  // Dynamically import the polyfill only when needed
  try {
    await import('https://cdn.jsdelivr.net/npm/invokers-polyfill@latest/dist/index.min.js');
    console.log('Invoker Commands polyfill loaded');
  } catch (err) {
    console.error('Error loading fallback:', err);
  }
}

Manual fallback (Traditional pattern)

If you prefer not to use a polyfill, you can use a combination of event delegation to dispatch events and a command registry to handle the actions. This is a common architectural pattern in traditional JavaScript development that remains highly efficient and scalable.

// 1. Define a registry of requested actions for cleaner logic
const commandRegistry = {
  '--spin': (target) => target.classList.toggle('is-spun'),
  '--grow': (target) => target.classList.toggle('is-grown'),
  '--reset': (target) => target.classList.remove('is-spun', 'is-grown'),
};

const supportsInvokers = 'commandForElement' in HTMLButtonElement.prototype;

// 2. The fallback: Dispatch events manually if native support is missing
if (!supportsInvokers) {
  document.addEventListener('click', (event) => {
    const button = event.target.closest('button[commandfor]');
    if (!button) return;

    const target = document.getElementById(button.getAttribute('commandfor'));
    const command = button.getAttribute('command');

    if (target && command) {
      target.dispatchEvent(new CustomEvent('command', {
        bubbles: true,
        detail: { command }
      }));
    }
  });
}

// 3. The unified listener: Registered directly on the target element
document.getElementById('action-target').addEventListener('command', (event) => {
  const command = event.command || event.detail?.command;
  const target = event.currentTarget;
  const action = commandRegistry[command];

  if (action) {
    action(target);
  }
});

Polyfilling the Popover Attribute

To support the popover attribute in older browsers, use the @oddbird/popover-polyfill.

MANDATORY: Feature detect popover support by checking for the popover property on the HTMLElement prototype. Conditionally initialize the polyfill only if native support is missing.

Option 1: Using a bundler Install the package via npm (npm install @oddbird/popover-polyfill). This method requires a bundler or import maps to resolve the module path.

// MANDATORY: Feature detect 'popover' on HTMLElement.prototype.
if (!('popover' in HTMLElement.prototype)) {
  import('@oddbird/popover-polyfill/fn').then(({ apply }) => {
    apply();
  });
}

Option 2: Using a CDN For projects without a bundler, dynamically import the polyfill directly from a CDN inside a <script type="module">.

<script type="module">
  // MANDATORY: Feature detect 'popover' on HTMLElement.prototype.
  // Conditionally load the popover-polyfill from a CDN only in browsers lacking native support.
  if (!('popover' in HTMLElement.prototype)) {
    import('https://unpkg.com/@oddbird/popover-polyfill@latest/dist/popover-fn.js').then(({ apply }) => {
      apply();
    });
  }
</script>

Popover Polyfill Limitations & Styling Caveats MANDATORY: Use :is() or :where() to combine :popover-open with the corresponding polyfill class, otherwise browsers that do not support :popover-open will throw away the entire rule.

[popover]:is(:popover-open, .\:popover-open) {
  display: block;
}