Invoker Commands API: Declarative UI Control

I'm here to share something genuinely useful that landed recently in browsers: the Invoker Commands API. This API provides a declarative way to control interactive elements with buttons, reducing JavaScript boilerplate for common UI patterns like dialogs and popovers.

Historically, if you wanted a button to open a modal dialog or toggle a popover, you'd reach for JavaScript. You'd grab the button, add an event listener, find the target element, and then call its showModal() or togglePopover() method. It worked, but it meant waiting for your JavaScript to download and execute, and it added to your bundle size. The web platform is now giving us a more declarative way to handle this, moving that responsibility back to the browser.

What are Invoker Commands?

The Invoker Commands API introduces two new HTML attributes, commandfor and command, that you apply directly to a <button> element. These attributes allow a button to control other interactive elements on the page without needing any JavaScript. This means improved initial page interactivity, as the user does not have to wait for JavaScript to download and execute to make these buttons interactive.

Think of it like this:

commandfor: This attribute turns your <button> into a "command invoker" and tells the browser which element it should control. Its value is the id of the target element.
command: This attribute specifies what action the button should perform on the commandfor element.

This declarative approach can complement and in many cases, replace older methods like popovertargetaction and popovertarget, offering a unified and more powerful way to manage button interactions.

Practical Mini Build: Open Dialogs and Popovers

Let's build a simple HTML file that demonstrates how to open both a popover and a modal dialog using only these new attributes.

Step-by-Step Implementation

Create your HTML structure: We'll need buttons, a <dialog> element, and a <div> element with the popover attribute.
Link buttons to targets: Use commandfor to point to the id of your target element.
Specify actions: Use command with the appropriate built-in values for popovers and dialogs.

Here's the complete working code for a single index.html file:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Invoker Commands: Dialogs & Popovers</title>
    <style>
        body {
            font-family: sans-serif;
            margin: 2rem;
            display: flex;
            flex-direction: column;
            gap: 1rem;
            align-items: flex-start;
        }

        dialog {
            border: 1px solid #ccc;
            padding: 2rem;
            border-radius: 8px;
            box-shadow: 0 4px 8px rgba(0,0,0,0.1);
            background-color: white;
        }

        dialog::backdrop {
            background: rgba(0, 0, 0, 0.5);
            backdrop-filter: blur(5px);
        }

        [popover] {
            border: 1px solid #ddd;
            padding: 1rem;
            border-radius: 4px;
            box-shadow: 0 2px 4px rgba(0,0,0,0.05);
            background-color: #f9f9f9;
        }

        [popover]:not(:popover-open) {
            visibility: hidden; /* Hide popovers when not open */
        }
    </style>
</head>
<body>

    <h1>Invoker Commands: Declarative UI</h1>

    <h2>Popover Example</h2>
    <button commandfor="myPopover" command="toggle-popover">
        Toggle Popover
    </button>
    <div id="myPopover" popover>
        <p>This is a popover controlled declaratively!</p>
        <button commandfor="myPopover" command="hide-popover">
            Close Popover
        </button>
    </div>

    <h2>Modal Dialog Example</h2>
    <button commandfor="myDialog" command="show-modal">
        Show Modal Dialog
    </button>
    <dialog id="myDialog">
        <h3>This is a Modal Dialog</h3>
        <p>It blocks interaction with the rest of the page until dismissed.</p>
        <p>Press ESC or click the button to close it.</p>
        <button commandfor="myDialog" command="close">
            Close Dialog
        </button>
    </dialog>

    <h2>Custom Command Example</h2>
    <button commandfor="my-img" command="--rotate-left">Rotate left</button>
    <button commandfor="my-img" command="--rotate-right">Rotate right</button>
    <img id="my-img" src="photo.jpg" alt="A sample image" style="transition: rotate 0.3s ease;"/>

    <script>
        // Custom Command JavaScript
        const myImg = document.getElementById("my-img");
        myImg.addEventListener("command", (event) => {
            if (event.command === "--rotate-left") {
                myImg.style.rotate = "-90deg";
                console.log("Custom command: --rotate-left received!");
            } else if (event.command === "--rotate-right") {
                myImg.style.rotate = "90deg";
                console.log("Custom command: --rotate-right received!");
            }
        });

        // Basic feature detection (optional, for progressive enhancement)
        if (!Object.hasOwn(HTMLButtonElement.prototype, "commandfor")) {
            console.warn("Invoker Commands API not supported in this browser. Consider a polyfill or fallback JS.");
            // Example fallback for a popover (you'd need to manually manage display/accessibility)
            const fallbackPopoverButton = document.querySelector('button[commandfor="myPopover"]');
            const fallbackPopover = document.getElementById('myPopover');
            if (fallbackPopoverButton && fallbackPopover) {
                fallbackPopoverButton.onclick = () => {
                    if (fallbackPopover.style.visibility === 'hidden' || fallbackPopover.style.visibility === '') {
                        fallbackPopover.style.visibility = 'visible';
                        fallbackPopover.style.opacity = '1';
                    } else {
                        fallbackPopover.style.visibility = 'hidden';
                        fallbackPopover.style.opacity = '0';
                    }
                };
            }
        }
    </script>
</body>
</html>

Explanation:

Popover:
- The <div> with id="myPopover" also has the popover global attribute. This attribute designates it as a popover element, handling its visibility and top-layer behavior.
- The "Toggle Popover" button uses commandfor="myPopover" and command="toggle-popover". This tells the browser to toggle the visibility of the element with id="myPopover".
- Inside the popover, a "Close Popover" button uses commandfor="myPopover" and command="hide-popover" to explicitly close it.
- The popover attribute on its own (without a value) defaults to popover="auto", which means it can be "light dismissed" (closed by clicking outside or pressing Escape), and usually only one auto popover is shown at a time.
Modal Dialog:
- The <dialog> element with id="myDialog" is inherently designed for modal behavior.
- The "Show Modal Dialog" button uses commandfor="myDialog" and command="show-modal". This opens the dialog as a modal, preventing interaction with the rest of the page until it's closed.
- Inside the dialog, a "Close Dialog" button uses commandfor="myDialog" and command="close" to dismiss it. The browser also handles closing the dialog when the Escape key is pressed.
Custom Commands:
- The command attribute isn't limited to built-in actions. You can define custom commands by prefixing their names with --, similar to CSS custom properties.
- The my-img element listens for a command event. This event fires on the element referenced by commandfor.
- The JavaScript code checks event.command to determine which custom action (--rotate-left or --rotate-right) was triggered and applies the corresponding style. This allows you to create declarative APIs for your custom components, reducing the need for explicit event listeners on the buttons themselves.

Gotchas and Considerations

Browser Support

The Invoker Commands API, along with the commandfor and command attributes, achieved "Baseline" status in December 2025. This means it is supported across all major browsers, including Chrome (135+), Edge (135+), Firefox (144+), and Safari (26.2+).

However, if your audience includes users on older browser versions, you will need a fallback.

Fallback for Older Browsers

For browsers that don't support the Invoker Commands API, you'd typically fall back to traditional JavaScript event listeners. The example code includes a simple feature detection check using Object.hasOwn(HTMLButtonElement.prototype, "commandfor") and a basic JavaScript fallback for the popover. A more robust solution would involve a polyfill if you need consistent behavior across all older browsers, or a more comprehensive progressive enhancement strategy. Be aware that polyfills for this API might not fully replicate native behavior, especially concerning ARIA states and focus management.

Permissions and HTTPS

The Invoker Commands API itself doesn't introduce new permission prompts or strict HTTPS requirements beyond what's standard for web platform features. Dialogs and popovers are generally considered safe UI elements. However, for any website in production today, HTTPS is a fundamental security and performance requirement, so you should always be serving your content over HTTPS regardless of whether you're using this API.

Accessibility (A11y)

One of the significant advantages of the Invoker Commands API is that the browser handles much of the accessibility automatically. When you use commandfor and command with built-in actions like show-modal or toggle-popover, the browser manages focus trapping, focus restoration on close, Escape key handling, and the necessary ARIA attributes (like aria-expanded). This vastly simplifies building accessible interactive components compared to writing all that logic manually in JavaScript.

Custom Commands and JavaScript

While the core benefit is reducing JavaScript, the ability to define custom commands using the command event handler means you can still leverage this declarative pattern for more complex interactions where pure HTML isn't enough. This provides a clean separation: HTML declares what command to send, and JavaScript listens for how to execute it on the target element.

What to keep an eye on

Full ecosystem adoption: While major browsers support it, tooling and frameworks might take time to fully integrate and promote this API.
New built-in commands: The specification might expand to include more built-in commands for other interactive elements like <details> or media controls.
Polyfills: If you need to support a very broad range of older browsers, keep an eye on the maturity and completeness of polyfills for this API.