aria-actions

at a glance

why it exists

Many common UI patterns involve secondary actions — the close button on a tab, reply/forward/delete buttons on an email row, a mute button on a video call tile. Assistive-technology discovery of these related actions is a common pain point: when a screen-reader user focuses the tab, they are not made aware of its close button at all. aria-actions lets the composite element reference the action elements directly so the AT can announce and activate them. The ChromeStatus entry notes FluentUI is ready to adopt the feature once available, and Firefox shipped it (in Firefox 146, UIA mappings in 148) with a positive standards position: the functionality has long been available to native mobile and desktop applications.

syntax

The attribute takes a space-separated ID reference list — the ids of one or more elements whose activation performs an action relevant to the current element:

<div role="tab" aria-actions="close-button-id">Quarterly report</div>
<button id="close-button-id" aria-label="Close tab">×</button>

Formal characteristics (from the ARIA PR #1805 preview):

author requirements

The ARIA PR text places exact obligations on authors and user agents:

• Authors MUST ensure that elements referenced by aria-actions have an accessible name.
• Authors MUST ensure that related action elements respond to a click event and are not limited to modality-specific activation such as keyup or touchend.
• Authors MUST ensure each referenced action element is either directly navigable with the keyboard or has a keyboard shortcut to activate it when focus is on the referencing element.
• Authors MUST NOT define an empty string value (aria-actions="") on elements that do not have actions.
• Authors SHOULD ensure that related action elements are visible and activatable when the current element has DOM focus.
• Authors SHOULD set aria-actions="" on the referencing element when it is not focused, if the related action elements will not exist in the DOM until the element receives focus — this lets AT surface the availability of actions for interactions that do not trigger DOM focus.
• User agents SHOULD use the accessible names of referenced elements as the action names exposed in the platform accessibility API.
• User agents MUST NOT expose aria-actions if the author MUSTs above are not followed.

Accessible-name interaction (per the WPT accessible-name tests): the referencing element's own accessible name excludes the referenced action target's content, and the target's own accessible name is computed normally (e.g. its aria-label wins over its text content) — that target name is what the AT surfaces as the action label, so it must stay stable.

platform accessibility API mappings

The core-aam section of the PR defines how the attribute maps to each platform accessibility API. Referenced targets that are not exposed in the accessibility tree are not added as actions, but the presence signal (has-actions:true) is still always exposed when the attribute is set:

Concrete result for the tab example in examples: focusing the tab's accessible node reports one available action whose localized name is the button's accessible name:

// IAccessible2 / ATK view of the tab accessible:
nActions        = nActions + 1   // one referenced, tree-exposed target
name            = "custom_close-tab-1"  // DOM id, custom_ prefix
localizedName   = "Close tab"           // target's accessible name
doAction(i)     -> behaves as doAction(0) on the close button
has-actions     = true           // exposed even if target leaves the tree

examples

A tab strip where each tab exposes its close button as an action. The AT can announce “Quarterly report” with an available “Close tab” action, and activate it without the user hunting for the button:

<div role="tablist" aria-label="Open documents">
  <div role="tab" tabindex="0" aria-selected="true"
       aria-actions="close-tab-1">
    Quarterly report
    <button id="close-tab-1" aria-label="Close tab">×</button>
  </div>
</div>

<script>
  // The action element responds to click — activation via AT
  // dispatches the same click as pointer activation.
  document.getElementById('close-tab-1')
    .addEventListener('click', (e) => {
      e.stopPropagation();
      closeTab(e.currentTarget.closest('[role="tab"]'));
    });
</script>

Multiple actions use a space-separated list — an email row referencing reply, forward, and delete buttons: aria-actions="reply-btn forward-btn delete-btn". Set the references from script with the ariaActionsElements IDL reflection: tab.ariaActionsElements = [closeButton].

browser compatibility

No BCD entry exists yet for aria-actions/ariaActionsElements (checked api/Element, api/ElementInternals, and api/_mixins/ARIAMixin paths, 2026-07-28) — this interim table is built from the linked vendor sources and is labelled as such:

security and privacy

The attribute is a discovery-only accessibility bridge: it exposes to assistive technologies references between elements that already exist in the DOM, and its accessible-name behavior reuses names authors already publish (the WPT tests pin that the target's own name stays stable and is excluded from the host's name). It introduces no new script-observable capability, no storage, and no cross-origin surface; activation of a referenced action dispatches the same click the element already responds to. The ChromeStatus entry describes it as a small, discovery-only accessibility feature.

specifications

No TAG review; the ChromeStatus entry records the reasons: the ARIA specification work is largely accepted, Firefox has already shipped, Safari implements behind a flag, and the feature is a small discovery-only accessibility addition.

see also

• gendn — ariaActionsElements IDL member reference
• Chrome Platform Status — aria-actions
• w3c/aria PR #1805 — feat: aria-actions addition to the ARIA spec (resolves w3c/aria #1440)
• WPT results — wai-aria/aria-actions (4 tentative test files)
• Mozilla standards position — positive, shipped · WebKit standards position — in development
• blink-dev Intent to Prototype · Intent to Ship
• Chromium aria_relationship_attributes.idl (verbatim IDL) · runtime_enabled_features.json5 (AriaActions flag)
• Chrome Platform Showcase — interactive demos for this feature