Accessibility violation: Tippy.js adds aria-expanded to <span> with role="tooltip"

Created on 28 March 2025, about 1 month ago

Problem/Motivation

Tooltips in Webform use a &lt;span&gt; element with role="tooltip" and tabindex="0", which is keyboard-focusable but not an interactive element.
When using Tippy.js with interactive: true, the library automatically adds aria-expanded to the trigger.

This causes an accessibility violation because aria-expanded is not valid on non-interactive elements like a &lt;span&gt; with role="tooltip".
This issue is flagged by accessibility tools such as Siteimprove.

Steps to reproduce

  1. Enable the Webform module.
  2. Add a form element with help text.
  3. Inspect the DOM: a &lt;span&gt; with role="tooltip" is rendered as the help icon.
  4. Note that Tippy.js adds aria-expanded="false" to that element.
  5. Run an accessibility audit using Siteimprove.
  6. The audit flags the use of aria-expanded on the &lt;span&gt; as an invalid ARIA attribute.

Proposed resolution

Explicitly disable the automatic addition of aria-expanded in the Tippy.js configuration by setting:

aria: {
  expanded: null
}

This prevents Tippy.js from injecting the aria-expanded attribute, resolving the accessibility violation while still allowing tooltips to be triggered from a &lt;span&gt;.

Alternative approach: Replace the &lt;span&gt; element with a &lt;button&gt; element to improve semantic accessibility. A &lt;button&gt; is a natively interactive element and is compatible with attributes like aria-expanded, making it a better choice when tooltips are triggered via focus or click.

However, to minimize UI and markup changes, this patch preserves the current &lt;span&gt; and disables the problematic ARIA attribute instead.

Remaining tasks

  • Apply the fix in webform.element.help.js.

User interface changes

None. Tooltip behavior remains unchanged visually.

API changes

None.

Data model changes

None.

🐛 Bug report
Status

Needs review

Version

6.3

Component

Accessibility

Created by

🇪🇸Spain marthinal

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Merge Requests

Comments & Activities

  • Issue created by @marthinal
  • 🇺🇸United States jrockowitz Brooklyn, NY

    I am not sure this is resolvable. Changing the tooltip's HTML tag will cause visual regression on the sites targeting the SPAN tags. You might have to use the patch AS-IS.

  • 🇪🇨Ecuador jwilson3

    My understanding is that the patch specifically does not change the tag. (Changing the tag to a <button> was proposed as the "proper" alternate solution, but the approach in the patch as currently written does not change the tag, just removes the inappropriate aria-expanded.

  • 🇮🇳India rakesh.regar Rajasthan, India

    rakesh.regar made their first commit to this issue’s fork.

  • Pipeline finished with Success
    26 days ago
    Total: 590s
    #467253
  • 🇺🇸United States jrockowitz Brooklyn, NY

    The patch removes the expanded attribute which I think improves the accessiblity for screen readers.

    Even though a machine/automated review says the tag + attributes is invalid, it does not mean we should remove the attribute to pass an automated test.

  • 🇪🇨Ecuador jwilson3

    the expanded attribute [...] improves the accessiblity for screen readers.

    This is true, but the ARIA5 rules say that to be able to use the aria- attributes, you have to have an element with the correct role. By default, <span> has no semantic meaning—it's effectively role="presentation" or role="none" in ARIA terms unless styled or scripted to behave otherwise.

    Ideally, we'd switch to a <button>, but that could break themes that (incorrectly) target the <span> directly instead of using a class. Would changing the tag—and potentially breaking CSS—be considered an API change requiring a major version bump?

    If so, to resolve the issue, keep screen readers and machines happy, and avoid a major bump, what if we simply add role="button" to the <span> and ensure it behaves like a native button, including being focusable (tabindex="0") and keyboard-interactive (handling Enter/Space key events).

    References:
    WCAG 2.2: Technique ARIA5: Using WAI-ARIA state and property attributes to expose the state of a user interface component

Production build 0.71.5 2024