Invoker Commands (Explainer)

• Authors: Keith Cirkel

Invoker ButtonsSection titled Invoker%20Buttons

Pitch in CodeSection titled Pitch%20in%20Code

<button command="show-modal" commandfor="my-dialog">This opens a dialog</button>

<dialog id="my-dialog">This is the dialog</dialog>

IntroductionSection titled Introduction

Adding commandfor and command attributes to <button> and elements would allow authors to assign behaviour to buttons in a more accessible and declarative way, while reducing bugs and simplifying the amount of JavaScript pages are required to ship for interactivity. Buttons with command will - when clicked, touched, or enacted via keypress - dispatch a CommandEvent on the element referenced by commandfor, with some default behaviours.

BackgroundSection titled Background

All elements within the DOM are capable of having interactions added to them. A long while ago this took the form of adding inline JavaScript to an event attribute, such as <button onclick="other.open()"></button>. Inline JavaScript has (rightly so) fallen out of favour due to the security and maintainability concerns. Newer pages may instead introduce more JavaScript to imperatively discover elements and call addEventListener('click', ...) to invoke the same behaviour. These patterns reduce developer experience and introduce more boilerplate and friction, while remediating security and maintainability concerns. Some frameworks attempt to reintroduce the developer experience of inline handlers by introducing new JavaScript or HTML shorthands, such as React’s onClick={...}, Vue’s @click=".." or HTMX’s hx-trigger="click".

Handling clicking is only half of the problem though, and this proposal doesn’t seek to re-invent click handlers. Dispatching an action to a related element on the click can also become chore-like depending on the framework of choice. Many frameworks recommend associating a click event with a state change and having the element to be invoked react to that state change. For example the React docs on Adding Interactivity attach click handlers which set state.

There has also been a rise in the desire to customise controls for components. Many sites, for example, introduce custom controls for File Uploads or dropdown menus. These often require a large amount of work to reintroduce the built in functionality of those controls, and often unintentionally sacrifice accessibility in doing so.

With the new popover attribute, we saw a straightforward declarative way to tell the DOM that a button was interested in being a participant of the popover interaction. popovertarget would indicate to a browser that if that button was interacted with, it should open the element the popovertarget value pointed to. This allows for popovers to be created and interacted with - in an accessible and reliable way - without writing any additional JavaScript, which is a very welcome addition. While popovertarget sufficiently captured the use case for popovers, it fell short of providing the same developer & user experience for other interactive elements such as <dialog>, <details>, <video>, <input type="file">, and so on. This proposal attempts to redress the balance.

TermsSection titled Terms

• Invoke/Invoked/Invoking: The action of Invoking refers to a complete press action of a button, using a Human Input Device (HID). If the HID is a mouse, this would be a click event. If the HID is a touch screen, this would be a press using a stylus or finger. If the HID is a keyboard this would be the Space or Enter (Carriage Return) key on the keyboard. For other HIDs such as eye tracking or pedals or game controllers, the equivalent expected “click” action should be used to invoke the element.
• Invoker: An invoker is a button element (that is a <button>, <input type="button">, or <input type="reset">) that has an commandfor and command attribute set.
• Invoker Target: An element which is referenced to by an Invoker, via the commandfor attribute.

Proposed PlanSection titled Proposed%20Plan

In the style of popovertarget, this document proposes we add commandForElement, and command as available attributes to <button>.

interface mixin CommandElement {
  [CEReactions] attribute Element? commandForElement;
  [CEReactions] attribute DOMString command;
};

HTMLButtonElement extends InvokerElement

The commandfor value should be an IDREF pointing to an element within the document. .commandForElement also exists on the element to imperatively assign a node to be the invoker target, allowing for cross-root invokers (in some cases, see the popovertarget attr-asociated element steps for more).

The command attribute (and the .command reflected property) is a freeform hint to the invoker target. Command can be a “built-in” action or a “custom” action. If command is not supplied then it is considered invalid and no action will take place, and no event will be fired.

Custom command values must start with a double dash (--), similar to the CSS “dashed-ident” syntax. This is a safe namespace to use, and browsers guarantee to never have built-in values starting with --. The only browser behaviour for those values will be dispatching a CommandEvent on the invokee. This allows web developers to create custom Invoke actions for their components.

Built-in interactive elements have built-in behaviours (detailed below) which are determined by the command attribue/property. The built-in names must not start with a -.

Valid commands (that is: custom commands or a valid built-in) will dispatch CommandEvents, allowing custom code to take control of invocations (for example calling .preventDefault() or executing custom side-effects).

Invokers will dispatch an CommandEvent on the Invokee (the element referenced by commandfor) when the element is Invoked. The CommandEvent’s type is always command. The event also contains an source property that will reference button that was enacted causing the CommandEvent to fire. The dispatched CommandEvents are always non-bubbling, composed, trusted, cancellable events.

[Exposed=Window]
interface CommandEvent : Event {
  constructor(CommandEventInit invokeEventInit);
  readonly attribute Element source;
  readonly attribute DOMString type = "command";
  readonly attribute DOMString command;
};
dictionary CommandEventInit : EventInit {
  DOMString command = "";
  Element source;
};

If an element also has both a popovertarget and the commandfor/command attributes set, then popovertarget must be ignored: command takes precedence.

If a <button> is a form participant, or has type=submit, then command must be ignored. It also must not submit the form it is attached to. Buttons like this are “author errors”, and browsers may issue warnings in the developer console explaining to the developer why this button doesn’t work.

This means a <button> with command/commandfor that is inside a form must also have type=button.

Example CodeSection titled Example%20Code

PopoversSection titled Popovers

When pointing to a popover, commandfor acts much like popovertarget, allowing the toggling of popovers.

<button commandfor="my-popover" command="toggle-popover">Open Popover</button>
<!-- Effectively the same as popovertarget="my-popover" -->

<div id="my-popover" popover="auto">Hello world</div>

DialogsSection titled Dialogs

When pointing to a <dialog>, command can toggle a <dialog>’s openness.

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

<dialog id="my-dialog">
  Hello world!

  <button commandfor="my-dialog" command="close">Close</button>
</dialog>

DetailsSection titled Details

Note: Invokers targeting a <details> element has been deferred from the initial release.

When pointing to a <details>, commandfor can toggle a <details>’ openness.

<button commandfor="my-details" command="open">Open Details</button>
<!-- Can be used to replicate the `<summary>` interaction -->

<details id="my-details">
  <summary>Summary...</summary>
  Hello world!
</details>

Customizing input type=fileSection titled Customizing%20input%20type%3Dfile

Note: Invokers targeting a <input> element has been deferred from the initial release.

Pointing commandfor to an <input type="file"> can act the same as the rendered button within the input; and can be used to declare a customised alternative button to the input’s button.

<button commandfor="my-file" command="show-picker">Pick a file...</button>

<input id="my-file" type="file" />

Customizing video/audio controlsSection titled Customizing%20video/audio%20controls

Note: Invokers targeting <audio> and <video> elements has been deferred from the initial release.

The <video> and <audio> tags have many interactions, here commandfor shines, allowing multiple buttons to handle different interactions with the video player.

<button commandfor="my-video" command="play-pause">Play/Pause</button>
<button commandfor="my-video" command="toggle-muted">Mute/Unmute</button>

<video id="my-video"></video>

Custom behaviourSection titled Custom%20behaviour

Invokers will dispatch events on the Invokee element. Using a dash in the command allows for custom JavaScript to be triggered without having to wire up manual event handlers to the Invokers.

<!-- Custom commands must contain a double dash! -->
<button commandfor="my-custom" command="--my-frobulate">Frobulate</button>

<div id="my-custom"></div>

<script>
  document.getElementById("my-custom").addEventListener("command", (e) => {
    if (e.command === "--my-frobulate") {
      alert("Successfully frobulated the div");
    }
  });
</script>

DefaultsSection titled Defaults

Depending on the target set by commandfor, invoking the button will trigger additional behaviours alongside the event dispatch, depending on the value of command. The following table represents how built-in invocations on specific element types are handled.

When the command attribute is missing it will default to an invalid state.

Further behaviours have been proposed, but need further design on exactly how they will behave based on implications such as accessibility, security, interactivity, and how the button may need to respond to such actions.

Note: The above tables are an attempt at wide coverage, but ideas are welcome. Please submit a PR if you have one!

Further to the initial ship we’re also exploring implicit command or implicit commandfor values where the value can easily be inferred.

AccessibilitySection titled Accessibility

For built-in behaviours command attribute maps to specific accessibility mappings which are placed on the button. The button may also use the commandfor referenced element to gather other details (for example the state of the element) to reflect that state on the button.

These mappings will happen implicitly on the browsers Accessible Nodes, and so while (for simplicity) this secion refers to various aria- attributes, buttons will not sprout these attributes in the DOM, but the effective equivalent will be exposed to Assistive Technologies.

Buttons with command=toggle-popover, command=hide-popover, or command=show-popoverSection titled Buttons%20with%20command%3Dtoggle-popover%2C%20command%3Dhide-popover%2C%20or%20command%3Dshow-popover

Buttons with these popover commands will implicitly receive aria-details=IDREF, where IDREF matches that of the commandfor attribute, under certain conditions while the popover is in the showing state.

Browsers are expected to omit aria-details based on heuristics where it is redundant, such as the contents of the popover being the next accessibility sibling to the invoking element, or while the popover’s contents are not traversable, such as when it is hidden, or not in the DOM.

Browsers should also omit aria-details when the invoking button is a descendant of the popover it refers to, for example a close button inside the popover.

Buttons will also implicitly receive an aria-expanded value. The state of the aria-expanded value will map to the state of the popover. When the popover is open the button will have aria-expanded="true", when closed, aria-expanded="false". If the button is an descendant of the popover then it will be explictly set to aria-expanded="undefined", indicating to assistive technology that the expanded state is not applicable to this button. This attribute will be recomputed whenever the popover changes state, such that the button always reflects the state of expansion.

Buttons with these popover commands will also have focus restored to the button when the popover closes. This will require the popover keeping a reference to the opening button so that it can return the focus to that button.

Buttons with command=show-modalSection titled Buttons%20with%20command%3Dshow-modal

Buttons with this dialog command will also have focus restored to the button when the dialog closes. This will require the dialog keeping a reference to the opening button so that it can return the focus to that button.

Buttons with command=closeSection titled Buttons%20with%20command%3Dclose

Buttons with this dialog command will implicitly receive aria-details=IDREF, where IDREF matches that of the commandfor attribute, while the dialog is in the showing state, and the button is not a descendant of the dialog.

Buttons will also implicitly receive an aria-expanded value, if they are not a descendant of the commandfor= referenced element. The state of the aria-expanded value will map to the state of the dialog’s openness. When the dialog is open the button will have aria-expanded="true", when closed, aria-expanded="false". This will be recomputed whenever the dialog changes state, such that the button always reflects the state of openness.

Other built-in command= typesSection titled Other%20built-in%20command%3D%20types

The above commands are the core built-in command types which will be initially shipping. Further built-in commands will be proposed on a case-per-case basis, and additional aria or other logic will be considered with those at the time.

Custom command= typesSection titled Custom%20command%3D%20types

Custom command types have accessibility requirements which will be hard to determine based on the presence of the button and invokee alone. Consequently, it is left to the implementer or user of the custom command to assign appropriate aria markup to these buttons.

Elements with commandfor= but no command=Section titled Elements%20with%20commandfor%3D%20but%20no%20command%3D

In this current proposal, elements without a command= attribute are considered “author errors”; they will do nothing when invoked. These buttons will recieve no additional implicit aria states.

Invokers and Custom ElementsSection titled Invokers%20and%20Custom%20Elements

As the underlying system for invoke elements uses event dispatch, Custom Elements can make use of CommandEvent for their own behaviours. Consider the following:

<button commandfor="my-element" command="--spin-widget">
  Spin the widget
</button>

<spin-widget id="my-element"></spin-widget>
<script>

customElements.define(
    "spin-widget",
    class extends HTMLElement {
      connectedCallback() {
        this.addEventListener("command", (e) => {
          if (e.command === "--spin-widget") {
            this.spin();
          }
        });
      }
    },
  );
</script>

SecuritySection titled Security

This proposal adds new capabilities in that elements can be interacted with using HTML where prior these required scripting (read: JS). Care has been taken within this proposal to ensure there are no substantially new security implications, and that the risk is kept low.

In general, we should not grant significant new capabilities with or without scripting, and seek other ways to mitigate security concerns.

Invokers, by design, have two security affordances:

• Without scripting, they require user interaction - the invoker button needs to be clicked for the browser to fire an Invoke Event. Scripts are able to synthesise the InvokeEvent, or the click event on the button - but scripts are already capable of causing the same interactions without Invokers.
• The invoketarget takes an IDREF which must reference an ID within the same document. invokeTargetElement can be assigned a cross-root element, but this requires scripting which means all actions are already possible.

To go into more detail, below is a brief summary of the security considerations per interaction:

PopoversSection titled Popovers

This proposal allows opening and closing popovers with invoketarget. This is already possible with popovertarget, and so there is no new capability here.

DialogsSection titled Dialogs

This proposal allows opening and closing <dialog> elements with invoketarget. While this is new capability (prior to this proposal scripting is required), it poses the same security considerations as popovers in that it toggles the visiblity of a new element. Modal dialog elements are also placed on the “top layer” which means they occlude other content. This is already possible with popovers, which are also placed on the top layer, so while buttons to open <dialog> elements is a new capability, it is not a novel new security threat considering attackers could already craft a popover.

Modal dialogs also trap focus, such that focus can only be moved within elements inside the dialog or the browser native controls (such as the URL bar). This is considered to not pose a significant threat as the invoking button requires user activation, the dialog cannot render outside of the document frame (iframe or browser window) and so cannot occlude the browsers Chrome, and there are built in gestures to close a dialog (such as the Esc key via a CloseWatcher) that cannot be opted out of with or without invokers.

Details (proposed follow-on)Section titled Details%20%28proposed%20follow-on%29

This proposal aims to allow opening and closing <details> elements with invoketarget. This is not considered to be new capability, as it is already possible to do this with the <summary> element.

Input (proposed follow-on)Section titled Input%20%28proposed%20follow-on%29

It should be noted that input pickers (like the file picker dialog) render native controls outside of the bounds of the document frame (iframe or browser window). Due to this, the security implications of invoking these elements should be carefully considered.

Scripts can call .showPicker() on form elements, and the picker will open. There are some cross-origin restrictions, for example calling .showPicker() on elements in a cross-origin context only works for <input type=file> or <input type=color>.

It is also possible to wrap an <input> in a <label>, where invoking the label will open the picker. This is quite common practice when trying to style <input type=file> for example; dressing the <label> to look like a <button> and hiding the <input>.

This proposal allows showing the pickers of input elements, for example an invoker can target an <input type=file> and clicking the invoker will open the operating systems file picker dialog. As stated above, this is already possible with <label> elements, but care should be taken to ensure that the same cross-origin restrictions apply for Invokers as they do for scripting.

Fullscreen elements (proposed follow-on)Section titled Fullscreen%20elements%20%28proposed%20follow-on%29

Turning an element into a fullscreen needs to be carefully consdidered. Scripting already allows this via the .requestFullscreen() API which, as the name suggests, may not always be successful given the UA context. This API requires the document context to be active, for example requiring a user activation (this is true of invokers in the general case), it also requires the Permissions Policy to allow for this behaviour, and requires the element to not already be on the Top Layer.

All of these constraints should also be true for invokers opening fullscreen elements. This means the only significant new behavioural difference between an invoker opening a fullscreen element vs the existing behaviour which requires scripting, is that sanboxed iframes which disallow scripting but allow fullscreen may now declare a button that can fullscreen. Consider the following:

<iframe sandbox allow="fullscreen">
  <html id="invokee">
    <button commandfor="invokee" command="toggleFullscreen">Invoke</button> 
    <button onclick="invokee.requestFullscreen()">Go fullscreen</button>
  </html>
</iframe>

In this example, the <button onclick> will do nothing as the iframe is sandboxed and does not allow scripting. The <button invoketarget> will fullscreen the element, however, as the allow=fullscreen Permission Policy is enabled to allow fullscreen.

This is considered to be a low security threat, as it requires opt-in to the fullscreen Permission Policy explitly via iframe attributes or scripting. We will, however, continue to explore if this should be a possibility.

Media Elements (proposed follow-on)Section titled Media%20Elements%20%28proposed%20follow-on%29

This proposal allows video and audio elements to be controlled with buttons outside of the browsers native video controls. This includes playing, pausing, and toggling mute/unmute. Today this is only possible using scripting via the equivalent scripting APIs: .play() / .pause() / .muted=. These APIs are guarded by Permissions Policy, and so should the invoker equivalent. Some User Agents can be configured to reject calls to .play(), and this should also be true of invokers. As such the key new capability here is the ability to call these APIs without scripting enabled. This is effectively the same concern as fullscreen; the security model is guarded around the Permissions Policy.

There is also additional concern around the media element invokers being able to circumvent autoplay policies. Invokers should not be able to circumvent these. By design, invokers require a user interaction (clicking the button) and so this should not circumvent autoplay policies.

Further proposals…Section titled Further%20proposals%u2026

There are continued suggestions for new capabilities of Invokers, such as invoking picture-in-picture.

Each of these will need to be taken into consideration on a case-per-case basis. The following questions will need to be answered for each of these:

• Is it possible for the user to do this today with scripting?
• Is it possible for the user to do this today without scripting?
• Does this behaviour bypass scripting sandboxing rules, such as Permissions Policy or iframes?
• Does this enable buttons to invoke content that appears outside of the browser frame?

PAQ (Potentially Asked Questions)Section titled PAQ%20%28Potentially%20Asked%20Questions%29

Why the name command? Why not click?Section titled Why%20the%20name%20command%3F%20Why%20not%20click%3F

While click is a fairly well established name in the world of the web, it is quite specific to the action from a user gesture, whereas invoke events notify a related element that an interactive control is requesting action. In other words, a click happens on the element being interacted with - the invoker, while an invoke happens on the element the interactive control points to - the invokee.

If the invokee were to recieve click events from the interactive control, this would make it difficult to differentiate user interaction on the element vs on invoking elements. Take for example a video player; clicking on the area which renders the video may play/pause the video, but clicking on a video control may cause different behaviours on the video. The extra controls invoke an action on the video but the user gesture was performed on the controls themselves.

Invokers rely on click events for their behavior to work, and they are not intended to replace them. Instead, invokers enhance click events to drive behaviour on a different element. Consequently they need a new conceptual name for this. Given the opportunity to supply a new name, invoke was settled on.

Given the new conceptual model of “command” it stands to reason that all related concepts share the same name, as such commandfor and command were chosen rather than, say, clickfor/clickaction. Similarly the event class is named CommandEvent and the event name command.

Didn’t this used to be called invoke? What happened?Section titled Didn%u2019t%20this%20used%20to%20be%20called%20invoke%3F%20What%20happened%3F

The original proposal for Invoke Commands was to use the term invoke exhaustively through the API, and so the attributes were originally named invoketarget/invokeaction and the event named InvokeEvent with a type of invoke. This was deemed too abstract, and standards groups and web developers desired a simpler name. For those interested in the history, some conversation that lead to changing invoke to command starts around here: https://github.com/whatwg/html/issues/9625#issuecomment-2115718679

Do we have to always supply both? Can’t we make command or commandfor implicit?Section titled Do%20we%20have%20to%20always%20supply%20both%3F%20Can%u2019t%20we%20make%20command%20or%20commandfor%20implicit%3F

The original proposal had the concept of an “auto” command value which would determine an exlicit command based on various heuristics, such as the target element. This has been deferred for the initial ship, but may be explored further. This is considred out of scope for the initial ship, however.

We may also explore the possibility of making commandfor implicit, for example if a button is a descendant of a dialog, omitting commandfor may make sense. This is also considered out of scope for the initial ship.

What about adding Invoker defaults for <form>?Section titled What%20about%20adding%20Invoker%20defaults%20for%20%3Cform%3E%3F

Defaults for <form> are intentionally omitted as this proposal does not aim to replace Reset or Submit buttons. If you want to control forms, use those.

What about adding Invoker defaults for <a>?Section titled What%20about%20adding%20Invoker%20defaults%20for%20%3Ca%3E%3F

Defaults for <a> are intentionally omitted as this proposal does not aim to replace anchors. If you intend to produce a page navigation, use an <a> tag.

Why is command/commandfor limited to buttons?Section titled Why%20is%20command/commandfor%20limited%20to%20buttons%3F

This is by design, to allow for a “pit of success”; invoking actions on non-button elements such as <div>s or <a>s creates many problems, especially for non-interactive elements. While <a>s are interactive, they should only be used for page navigation and not for invoking other behaviours, and so command/commandfor should not be allowed.

Why isn’t input[type=submit] included?Section titled Why%20isn%u2019t%20input%5Btype%3Dsubmit%5D%20included%3F

This is not added by design. Submit inputs already have a default action: submitting forms. If you want a button to control the submission of a form, use input[type=submit], if you want a button to control invocation of something other than a form then you should use input[type=button].

Why is input[type=reset] included?Section titled Why%20is%20input%5Btype%3Dreset%5D%20included%3F

It may stand to reason that if input[type=submit] is excluded then so should input[type=reset], however, there are valid use cases to resetting a form at the same time as some other action, for example closing the dialog that contains a form:

<dialog id="my-dialog">
  <form>
    <input type="text" />
    <!-- This button closes the dialog _and_ resets the form -->
    <input type="reset" commandfor="my-dialog" command="close" value="Cancel" />
  </form>
</dialog>

What does this mean for popovertarget?Section titled What%20does%20this%20mean%20for%20popovertarget%3F

Whilst command/commandfor does replicate popovertarget’s functionality, the two will co-exist side by side for some while to enable a smooth transition.

It is, however, intended that commandfor will replace popovertarget leading to popovertarget’s eventual deprecation.

Why doesn’t command just call the JS API method?Section titled Why%20doesn%u2019t%20command%20just%20call%20the%20JS%20API%20method%3F

HTML attribute values have different casing to method names, so for example an attribute value of show-modal does not match the method name showModal(). This requires manual mapping to the respective methods, but browsers - under the hood - effectively map from these values to the respective methods. Similarly, custom commands must be prefixed with a double dash (--). It is possible to convert the dashed value to camel case, and use computed properties to call methods, if that’s desired:

<button commandfor="my-element" command="--spin-widget">
  Spin the widget
</button>

<spin-widget id="my-element"></spin-widget>
<script>
  customElements.define(
    "spin-widget",
    class extends HTMLElement {
      connectedCallback() {
        this.addEventListener("command", (e) => {
          const method = e.command
            .slice(2) // remove the double dash
            .replace(/(-\w)/g, c => c[1].toUpperCase()); // dash-to-camel case
          if (method in this) {
            this[method](event);
          }
        });
      }
      spinWidget(event) {
        // ...
      }
    },
  );
</script>

Command seems limited, what if I wanted to add arguments?Section titled Command%20seems%20limited%2C%20what%20if%20I%20wanted%20to%20add%20arguments%3F

Custom commands can be used in a freeform way, for your own elements. If you feel it necessary you can invent your own DSLs for passing extra data using this hint. For example:

<button commandfor="my-counter" command="--add-1">Add 1</button>
<button commandfor="my-counter" command="--add-2">Add 2</button>
<button commandfor="my-counter" command="--add-10">Add 10</button>

<input readonly id="my-counter" value="0" />

<script>
  const counter = document.getElementById("my-counter");
  counter.addEventListener("command", (e) => {
    let addMatch = /^--add-(\d+)$/.match(e.command);
    if (addMatch) {
      counter.value = Number(counter.value) + Number(addMatch[1]);
    }
  });
</script>

You can also leverage the buttons value attribute to effectively parameterise certain commands:

<button commandfor="my-counter" command="--add-num" value="1">Add 1</button>
<button commandfor="my-counter" command="--add-num" value="2">Add 2</button>
<button commandfor="my-counter" command="--add-num" value="10">Add 10</button>

<input readonly id="my-counter" value="0" />

<script>
  const counter = document.getElementById("my-counter");
  counter.addEventListener("command", (e) => {
    if (e.command == '--add-num') {
      counter.value = Number(counter.value) + Number(e.invoker.value);
    }
  });
</script>