feat(checks/label): support ARIA element internals properties by straker · Pull Request #5170 · dequelabs/axe-core

straker · 2026-06-15T21:58:39Z

Updates the checks/label directory to use the new getAriaValue, hasAriaValue, and getResolvedRefs functions where it makes sense.

Here's a report of the full directory:

checks/label/help-same-as-label - aria-describedby: replaced node.getAttribute + idrefs() with hasAriaValue + getResolvedRefs; since getResolvedRefs returns VirtualNodes, updated accessibleText(thing) to accessibleText(thing.actualNode)
checks/label/multiple-label - aria-labelledby: replaced idrefs() with getResolvedRefs; since VirtualNodes are returned, updated .includes(domNode) to .some(ref => ref?.actualNode === domNode)
checks/label/title-only - aria-describedby: replaced .attr() truthy check with hasAriaValue since only presence is needed
checks/label/alt-space-value - checks alt attribute, not an ARIA prop
checks/label/duplicate-img-label - compares accessible names, no direct ARIA attr access
checks/label/explicit - checks label[for] association, no ARIA attr access
checks/label/hidden-explicit-label - checks label visibility, no ARIA attr access
checks/label/implicit - checks implicit label wrapping, no ARIA attr access
checks/label/label-content-name-mismatch - computes accessible names, no direct ARIA attr access
checks/label/no-implicit-explicit-label - no direct ARIA attr access (in aria directory, not label)

Closes: #5146

Convert aria-describedby and aria-labelledby attribute reads in title-only, help-same-as-label, and multiple-label checks to use getResolvedRefs, hasAriaValue, and getAriaValue so that values set via ElementInternals are also detected.

chutchins25

Nice work — clean migration to the element-internals helpers, and the new testutils-element tests cover the internals path for each check. Two low-severity questions below, neither blocking.

chutchins25 · 2026-06-17T14:14:53Z

  const labelText = labelVirtual(virtualNode);
  const title = titleText(virtualNode);
-  const ariaDescribedBy = virtualNode.attr('aria-describedby');
+  const ariaDescribedBy = hasAriaValue(virtualNode, 'aria-describedby');


Not a blocker, just a consistency question — hasAriaValue is presence-based (it returns true for an empty aria-describedby=""), whereas the previous .attr('aria-describedby') truthy check treated an empty attribute as absent. So an element with an empty aria-describedby and no title/label would now flip title-only from false to true. Such an element has no accessible name anyway, so the practical impact is negligible — was the presence-based semantics (vs. value-truthy) intended here?

Agreed. This isn't right.

Resolved — switched to getAriaValue and check .value, so an empty aria-describedby is treated as absent again.

chutchins25 · 2026-06-17T14:14:53Z

    // make sure the ONE AT visible label is in the list of idRefs of aria-labelledby
-    const labelledby = idrefs(node, 'aria-labelledby');
-    return !labelledby.includes(ATVisibleLabels[0]) ? undefined : false;
+    const vNode = getNodeFromTree(node);


Not a blocker, just a simplification — getResolvedRefs accepts a raw DOM node and calls nodeLookup internally, so you can pass node directly and drop the getNodeFromTree import/call (const labelledby = getResolvedRefs(node, 'aria-labelledby')). Up to you if the intermediate vNode reads more clearly.

Resolved — passing node directly to getResolvedRefs and dropped the getNodeFromTree call.

WilcoFiers

See Chris's comment

…a-describedby Use getAriaValue instead of hasAriaValue so an empty aria-describedby is treated as absent, and simplify multiple-label to pass the DOM node directly to getResolvedRefs.

…abel

Resolved

Add coverage for the reflected ariaLabelledByElements property overriding aria-labelledby in the multiple-label check. getResolvedRefs already honors the property; this regression-tests the #4943 scenario. Tests adapted from #5187. Co-authored-by: JC Franco <jfranco@esri.com>

WilcoFiers

LGTM. I would suggest pulling the comment, but I don't feel strongly about that. Couple issues to open though.

WilcoFiers · 2026-07-14T10:40:46Z

+  // ariaLabelledByElements (reflected AOM property) coverage adapted from
+  // @jcfranco's work in #5187 (issue #4943)


Suggested change

// ariaLabelledByElements (reflected AOM property) coverage adapted from

// @jcfranco's work in #5187 (issue #4943)

We can do attribution in other ways. Doesn't belong in the code.

WilcoFiers · 2026-07-14T10:44:47Z

    const ATVisibleLabels = labels.filter(label =>
      isVisibleToScreenReaders(label)
    );
    // more than 1 AT visible label will fail IOS/Safari/VO even with aria-labelledby


I'm skeptical this is still true. Would you mind opening an issue for us to investigate?

Opened #5211 to investigate this.

WilcoFiers · 2026-07-14T10:48:08Z

+  const ariaDescribedBy = getAriaValue(virtualNode, 'aria-describedby');

-  return !labelText && !!(title || ariaDescribedBy);
+  return !labelText && !!(title || ariaDescribedBy?.value);


This is buggy (not new). We should consider building a proper accessibleDescription method and use that. Would you mind opening an issue for this?

Opened #5212 to track building a proper accessibleDescription method and switching this check to use it.

straker requested a review from a team as a code owner June 15, 2026 21:58

use virtual

ba16fb3

chutchins25 reviewed Jun 17, 2026

View reviewed changes

WilcoFiers previously requested changes Jun 18, 2026

View reviewed changes

chutchins25 added 2 commits June 18, 2026 13:48

fix(checks/label): preserve value-truthy semantics for title-only ari…

b015006

…a-describedby Use getAriaValue instead of hasAriaValue so an empty aria-describedby is treated as absent, and simplify multiple-label to pass the DOM node directly to getResolvedRefs.

Merge remote-tracking branch 'origin/develop' into internals-checks-l…

358bbb4

…abel

chutchins25 requested a review from WilcoFiers June 18, 2026 17:51

chutchins25 self-assigned this Jun 18, 2026

chutchins25 mentioned this pull request Jun 18, 2026

feat(commons/text): support form-associated labels via element internals #5182

Open

straker mentioned this pull request Jun 29, 2026

fix: honor ariaLabelledByElements in label resolution #5187

Closed

chutchins25 mentioned this pull request Jul 1, 2026

ElementInternals: Convert each subdirectory to use the new getAriaValue function #5044

Open

WilcoFiers approved these changes Jul 14, 2026

View reviewed changes

chutchins25 merged commit 21c5f8b into develop Jul 15, 2026
23 checks passed

chutchins25 deleted the internals-checks-label branch July 15, 2026 12:53

This was referenced Jul 15, 2026

Investigate whether multiple AT-visible labels still fail iOS/Safari/VoiceOver with aria-labelledby #5211

Open

title-only check approximates accessible description; build a proper accessibleDescription method #5212

Open

		// ariaLabelledByElements (reflected AOM property) coverage adapted from
		// @jcfranco's work in #5187 (issue #4943)

Uh oh!

Conversation

straker commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chutchins25 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

WilcoFiers left a comment

Choose a reason for hiding this comment

Uh oh!

WilcoFiers left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

straker commented Jun 15, 2026 •

edited

Loading