feat(commons/text): support form-associated labels via element internals by chutchins25 · Pull Request #5182 · dequelabs/axe-core

chutchins25 · 2026-06-18T18:11:54Z

Summary

Form-associated custom elements (static formAssociated = true + attachInternals()) can be labeled with native <label> elements, which the browser exposes through ElementInternals.labels. axe-core's accessible-name computation dropped these labels entirely, because:

nativeTextAlternative builds its naming methods from the element spec, and getElementSpec() returns {} for custom element names — so labelText was never invoked for a custom element.
Label resolution in labelText only looked at the DOM by id (label[for]) / ancestor wrapping.

This wires up the proposal's final step.

Changes

native-text-alternative.js — findTextMethods detects a form-associated custom element via ElementInternals and appends labelText.
label-text.js — labelText reads internals.labels directly when present (the authoritative, complete set of explicit + implicit labels), falling back to the existing DOM resolution otherwise.

ElementInternals.labels throws NotSupportedError on a custom element that isn't form-associated, so both reads are guarded with try/catch. Both paths are gated by the existing elementInternals run option — with the flag off, vNode.elementInternals is undefined and behavior is unchanged.

Why `internals.labels` (not the DOM lookup)?

It's the browser-authoritative association and is the complete set — it already includes the ancestor-wrapping label. Routing it through the existing explicit + implicit merge would count a wrapping label twice, so labelText uses the internals list exclusively when present.

Out of scope

checks/label (explicit/implicit) — no change needed. They resolve labels via label[for=id] / closest('label'), which already cover custom elements, and the label rule selector is input, textarea anyway. Matches the proposal ("rules that look at implicit/explicit labels will not need to be updated") and feat(checks/label): support ARIA element internals properties #5170 leaving those checks untouched.
Non-labelable custom elements with a stray <label for> — labelable-ness/role territory (ElementInternals: update implicitRole to use getElementInternals #5039), pre-existing.
getResolvedRefs (feat(dom/getResolvedRefs): new function to get the resolved virtual nodes of idrefs #5151) — native <label>/for association isn't an ARIA idref, so it doesn't apply here.

Testing

test/testutils.js — new shared testutils-form-element (form-associated).
label-text.js — explicit, implicit, multiple, implicit+explicit dedup, global-map protocol, non-form-associated fall-through, Shadow DOM.
native-text-alternative.js — explicit/implicit pickup, gating (non-form-associated gets no label), flag-off no-op.

No integration test added — this is a commons/text change with no rule/check edits; the nearest rule impact (aria-input-field-name on a role-bearing custom element) depends on role-via-internals selection (#5039), which isn't wired yet.

Closes #5045

Detect form-associated custom elements in nativeTextAlternative and add labelText, and resolve labels from internals.labels in labelText. Both are gated by the elementInternals run option. Closes issue #5045

Copilot

Pull request overview

This PR updates axe-core’s commons/text accessible-name computation to recognize native <label> associations for form-associated custom elements by leveraging ElementInternals.labels (when available and enabled via the existing elementInternals feature flag).

Changes:

Extend nativeTextAlternative to append labelText for form-associated custom elements detected via ElementInternals.
Update labelText to prefer internals.labels (authoritative explicit + implicit labels) and fall back to DOM-based lookup otherwise.
Add/expand test utilities and unit tests covering explicit/implicit/multiple labels, deduping, global map internals, and Shadow DOM scenarios.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`lib/commons/text/native-text-alternative.js`	Detects form-associated custom elements via internals and conditionally adds `labelText` as a naming method.
`lib/commons/text/label-text.js`	Uses `ElementInternals.labels` (guarded) to compute label text, falling back to existing DOM resolution.
`test/testutils.js`	Introduces `testutils-form-element` (form-associated) for label-related tests.
`test/commons/text/native-text-alternative.js`	Adds unit tests validating label pickup + feature-flag gating for form-associated custom elements.
`test/commons/text/label-text.js`	Adds unit tests for internals-based label resolution (including global map + Shadow DOM).
`test/commons/aria/get-role.js`	Adds regression tests clarifying presentational role inheritance behavior with ElementInternals roles.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…ociated-labels

- native-text-alternative: only add labelText when internals.labels is a real collection, so a plain internals object without labels can't add it - label-text / native-text-alternative tests: restore globalThis._elementInternals and axe._enableElementInternals via try/finally so a failed assertion can't leak state into later tests

straker · 2026-07-20T17:11:18Z

+      `);
+      // testutils-element is not form-associated, so reading internals.labels
+      // throws and we fall through to resolving label[for] from the DOM
+      assert.equal(labelText(target), 'My explicit label');


This is incorrect. If the element is not form associated then it doesn't get labels associated with it, so this should be an empty string.

We went through this logic, and this function is only called in noImplicitExplicitLabelEvaluate, which is only used in two rules: aria-input-field-name and aria-toggle-field-name. From the rules we want to check if any visually labels of the node (which is itself not a label element and thus isn't linked to the label to begin with) are included in the ARIA name for the element. This means that for the labelText function we want all nodes, even custom elements, to check the labels so we should fallback to the DOM lookup. So this test is correct but we should add a comment in the code to clarify this odd behavior.

Added a comment for clarification to our findings.

…d custom elements Explain why labelText resolves DOM <label>s for a non-form-associated custom element instead of returning '', per review feedback on #5182.

Resolved comments.

All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines. ## [4.13.0](v4.12.1...v4.13.0) (2026-08-05) ### Features - **aria-actions:** add aria-actions to allowed ARIA attributes ([#5200](#5200)) ([029655d](029655d)), closes [#4584](#4584) [#5199](#5199), references [#5215](#5215) [#5215](#5215) - **aria-allowed-attr:** flag deprecated ARIA attributes as needs-review ([#5246](#5246)) ([518f3cc](518f3cc)), closes [#3341](#3341) - **aria-prohibited-attr:** allow many elements to be named and disallow label and body from being named ([#5259](#5259)) ([d8b1ea5](d8b1ea5)) - **aria-roles:** add sectionheader and sectionfooter roles ([#5238](#5238)) ([c36c109](c36c109)), closes [#4734](#4734), references [#4734](#4734) - **aria/get-aria-value:** new function to get aria values of a node ([#5109](#5109)) ([a7d8f3e](a7d8f3e)), references [#5042](#5042) - **aria/has-attr-value:** new function to check if node has aria value ([#5136](#5136)) ([61f2624](61f2624)), references [#5109](#5109) - **aria:** support role=image as equivalent to role=img ([#5248](#5248)) ([5aa8aaf](5aa8aaf)), closes [#4656](#4656), references [#5272](#5272) - **checks/aria:** support ARIA element internals properties ([#5172](#5172)) ([9b7f754](9b7f754)) - **checks/label:** support ARIA element internals properties ([#5170](#5170)) ([21c5f8b](21c5f8b)) - **checks/navigation:** support ARIA element internals properties ([#5167](#5167)) ([2c3a98f](2c3a98f)) - **commons/aria:** support ARIA element internals properties ([#5171](#5171)) ([31f09e7](31f09e7)) - **commons/dom:** support ARIA element internals properties ([#5163](#5163)) ([f0a12cf](f0a12cf)) - **commons/forms:** support ARIA element internals properties ([#5165](#5165)) ([27a4686](27a4686)) - **commons/matches/fromPrimative:** deprecate in favor of correct spelling ([#5270](#5270)) ([31cfb2e](31cfb2e)) - **commons/text:** support ARIA element internals properties ([#5169](#5169)) ([e841a33](e841a33)) - **commons/text:** support form-associated labels via element internals ([#5182](#5182)) ([57cfe0a](57cfe0a)), closes [#5045](#5045), references [#5170](#5170) [#5039](#5039) [#5151](#5151) [#5039](#5039) - **dom/getResolvedRefs:** new function to get the resolved virtual nodes of idrefs ([#5151](#5151)) ([489cdea](489cdea)), references [#5109](#5109) - **element-internals:** enable ElementInternals by default ([#5284](#5284)) ([2740d42](2740d42)), closes [#5277](#5277) - **i18n:** Add Swedish locale ([#5190](#5190)) ([dcd13f2](dcd13f2)), references [#5189](#5189) - **matches:** add inSectioningContent, hasChild, and isSummaryForDetails matches ([#5262](#5262)) ([c47cdcd](c47cdcd)) - **rules:** support ARIA element internals properties ([#5168](#5168)) ([065baf7](065baf7)) - **standards/ariaAttrs:** add caseInsensitive property for attributes ([#5224](#5224)) ([bcd791c](bcd791c)) ### Bug Fixes - **aria-allowed-role:** allow roles on a non-details summary ([#5242](#5242)) ([3bd9875](3bd9875)), closes [#3911](#3911), references [#3443](#3443) [#3911](#3911) - **aria-allowed-role:** restrict figure roles with child figcaption ([#5240](#5240)) ([178a635](178a635)), closes [#3443](#3443) - **aria-prohibited-attr:** visible aria-labelledby requires review only ([#5285](#5285)) ([fd6fa9f](fd6fa9f)) - **axe.d.ts:** make enabled property of RuleMetadata optional ([#5129](#5129)) ([90fce18](90fce18)) - **color-contrast:** fix various stacking context bugs ([#5214](#5214)) ([d5e5b04](d5e5b04)), references [#8](#8) [#5213](#5213) - **gather-internals:** handle non-HTMLElement nodes ([#5161](#5161)) ([06e84c3](06e84c3)) - **get-selector:** escape control characters in attribute selectors ([#5273](#5273)) ([4b60ac5](4b60ac5)), closes [#5204](#5204) [#5204](#5204) - **image-alt:** allow whitespace alt on presentational images ([#5218](#5218)) ([c5dd0ef](c5dd0ef)), closes [#5216](#5216) - **landmark-unique:** exclude section/form with non-landmark roles from landmark match ([#5085](#5085)) ([c5fd013](c5fd013)), closes [#4722](#4722) [#5064](#5064) - name the image role in role-img-alt and svg-img-alt metadata ([#5279](#5279)) ([995a269](995a269)), closes [#5272](#5272), references [#5248](#5248) [#5248](#5248) - **standards:** update aria-errormessage and aria-details to be idrefs ([#5157](#5157)) ([fb94f8a](fb94f8a)) This PR was opened by a robot 🤖 🎉

chutchins25 self-assigned this Jun 18, 2026

chutchins25 requested a review from Copilot June 18, 2026 18:14

Copilot started reviewing on behalf of chutchins25 June 18, 2026 18:14 View session

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

b0fbb14

Detect form-associated custom elements in nativeTextAlternative and add labelText, and resolve labels from internals.labels in labelText. Both are gated by the elementInternals run option. Closes issue #5045

chutchins25 force-pushed the chut/5045-form-associated-labels branch from 74d3009 to b0fbb14 Compare June 18, 2026 18:16

Copilot AI reviewed Jun 18, 2026

View reviewed changes

Comment thread lib/commons/text/native-text-alternative.js

Comment thread test/commons/text/label-text.js

Comment thread test/commons/text/native-text-alternative.js

Merge remote-tracking branch 'origin/develop' into chut/5045-form-ass…

1fc6611

…ociated-labels

chutchins25 marked this pull request as ready for review June 30, 2026 15:08

chutchins25 requested a review from a team as a code owner June 30, 2026 15:08

chutchins25 marked this pull request as draft July 1, 2026 12:40

chutchins25 marked this pull request as ready for review July 1, 2026 12:49

chutchins25 requested review from WilcoFiers and straker July 20, 2026 14:31

straker previously requested changes Jul 20, 2026

View reviewed changes

docs(commons/text): clarify DOM label fallback for non-form-associate…

e6f85cd

…d custom elements Explain why labelText resolves DOM <label>s for a non-form-associated custom element instead of returning '', per review feedback on #5182.

straker approved these changes Jul 20, 2026

View reviewed changes

straker merged commit 57cfe0a into develop Jul 20, 2026
23 checks passed

straker deleted the chut/5045-form-associated-labels branch July 20, 2026 19:51

attest-team-ci mentioned this pull request Aug 5, 2026

chore(release): v4.13.0 #5288

Merged

coderabbitai Bot mentioned this pull request Aug 12, 2026

test: add vitest suite (dca, formatters, forms, a11y) SamuelIVX/Deltabase#220

Merged

Navigation Menu

Uh oh!

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

feat(commons/text): support form-associated labels via element internals#5182
straker merged 4 commits into
developfrom
chut/5045-form-associated-labels

chutchins25 commented Jun 18, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

straker Jul 20, 2026

Uh oh!

straker Jul 20, 2026

Uh oh!

chutchins25 Jul 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

chutchins25 commented Jun 18, 2026

Summary

Changes

Why internals.labels (not the DOM lookup)?

Out of scope

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

straker Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

straker Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

chutchins25 Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Why `internals.labels` (not the DOM lookup)?