Feature/aria labelledby support by flutter-zl · Pull Request #171040 · flutter/flutter

flutter-zl · 2025-06-23T21:57:56Z

Description

This PR implements comprehensive aria-labelledby support for Flutter Web, enabling complex accessible labels composed of multiple semantic parts. This significantly improves web accessibility by allowing developers to create structured, screen reader-friendly labels that follow WAI-ARIA best practices.

Problem Solved

#162094

Before: Flutter Web only supported single aria-label attributes, making it difficult to create complex form labels with multiple semantic components (e.g., field name + format instructions + requirement indicators).

After: Developers can now create rich, multi-part labels that screen readers can properly interpret and announce to users.

Demo app: https://labelledby-0618.web.app/

Test 1: Customer Name + Required Field (2 parts)

<input aria-labelledby="textfield-label-9-0 textfield-label-9-1" type="text">
<span id="textfield-label-9-0" aria-hidden="true" style="display: none;">Customer Name</span>
<span id="textfield-label-9-1" aria-hidden="true" style="display: none;">Required Field</span>

Test 2: Email + Format Instructions + Required (3 parts)

<input aria-labelledby="textfield-label-11-0 textfield-label-11-1 textfield-label-11-2" type="text">
<span id="textfield-label-11-0" aria-hidden="true" style="display: none;">Email Address</span>
<span id="textfield-label-11-1" aria-hidden="true" style="display: none;">Format: [email protected]</span>
<span id="textfield-label-11-2" aria-hidden="true" style="display: none;">Required</span>

Test 3: Submit Button + Keyboard Shortcut (Group semantics)

<flt-semantics role="group" aria-labelledby="label-13-0 label-13-1">
  <span id="label-13-0" aria-hidden="true" style="display: none;">Submit Form</span>
  <span id="label-13-1" aria-hidden="true" style="display: none;">Ctrl+Enter shortcut available</span>
  <flt-semantics role="button" tabindex="0">Submit</flt-semantics>
</flt-semantics>

Test 4: Complex Password Instructions (4 parts)

<input aria-labelledby="textfield-label-16-0 textfield-label-16-1 textfield-label-16-2 textfield-label-16-3" type="password">
<span id="textfield-label-16-0" aria-hidden="true" style="display: none;">Password Field</span>
<span id="textfield-label-16-1" aria-hidden="true" style="display: none;">Minimum 8 characters</span>
<span id="textfield-label-16-2" aria-hidden="true" style="display: none;">Must include uppercase, lowercase, and numbers</span>
<span id="textfield-label-16-3" aria-hidden="true" style="display: none;">Required for account security</span>

Test 5: Single Label Comparison (Falls back to aria-label)

<input aria-label="Regular single label field (should use aria-label)" type="text">

Pre-launch Checklist

I read the Contributor Guide and followed the process outlined there for submitting PRs.
I read the Tree Hygiene wiki page, which explains my responsibilities.
I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
I signed the CLA.
I listed at least one issue that this PR fixes in the description above.
I updated/added relevant documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is test-exempt.
I followed the breaking change policy and added Data Driven Fixes where supported.
All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

mdebbar

Looks good to me with a few minor suggestions.

I would like to make sure this also looks good to @chunhtai, especially the framework parts.

mdebbar · 2025-06-26T14:57:07Z

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/label_and_value.dart

+  // If labelParts are provided, use them instead of the regular label
+  if (labelParts != null && labelParts.isNotEmpty) {
+    final String labelPartsValue = labelParts
+        .where((String part) => part.trim().isNotEmpty)
+        .join(' ');
+    if (labelPartsValue.isNotEmpty) {
+      // Combine labelParts with value if both exist
+      final String combinedValue = <String?>[
+        labelPartsValue,
+        value,
+      ].whereType<String>().where((String element) => element.trim().isNotEmpty).join(' ');
+      return combinedValue.isNotEmpty ? combinedValue : null;
+    }
+  }
+
+  // Fallback to regular label + value logic
+  final String combinedValue = <String?>[
+    label,
+    value,
+  ].whereType<String>().where((String element) => element.trim().isNotEmpty).join(' ');


To simplify this a little bit:

Suggested change

// If labelParts are provided, use them instead of the regular label

if (labelParts != null && labelParts.isNotEmpty) {

final String labelPartsValue = labelParts

.where((String part) => part.trim().isNotEmpty)

.join(' ');

if (labelPartsValue.isNotEmpty) {

// Combine labelParts with value if both exist

final String combinedValue = <String?>[

labelPartsValue,

value,

].whereType<String>().where((String element) => element.trim().isNotEmpty).join(' ');

return combinedValue.isNotEmpty ? combinedValue : null;

}

}

// Fallback to regular label + value logic

final String combinedValue = <String?>[

label,

value,

].whereType<String>().where((String element) => element.trim().isNotEmpty).join(' ');

List<String?>? allParts;

// If labelParts are provided, use them instead of the regular label

if (labelParts != null && labelParts.isNotEmpty) {

final Iterable<String> validLabelParts = labelParts.where((String part) => part.trim().isNotEmpty);

if (validLabelParts.isNotEmpty) {

allParts = <String?>[...validLabelParts, value];

}

}

// Fallback to regular label + value

allParts ??= <String?>[label, value];

final String combinedValue = allParts

.whereType<String>()

.where((String element) => element.trim().isNotEmpty)

.join(' ');

mdebbar · 2025-06-26T15:49:06Z

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/label_and_value.dart

+      final String labelId = '$idPrefix-${semanticsObject.id}-$i';
+      labelIds.add(labelId);
+
+      DomElement? labelElement = containerElement.querySelector('#$labelId');


Instead of relying on querySelector, I suggest keeping a list of these span elements, _labelPartElements or something like that.

mdebbar · 2025-06-26T15:56:09Z

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/label_and_value.dart

+        final String oldLabelId = '$idPrefix-${semanticsObject.id}-$i';
+        containerElement.querySelector('#$oldLabelId')?.remove();


This would become:

_labelPartElements[i].remove();

and after the for loop:

_labelPartElements.length = labelParts.length;

mdebbar · 2025-06-26T15:57:48Z

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/label_and_value.dart

+    for (int i = 0; i < _previousLabelParts!.length; i++) {
+      final String labelId = '$idPrefix-${semanticsObject.id}-$i';
+      containerElement.querySelector('#$labelId')?.remove();
+    }


this would become:

_labelPartElements.forEach((DomElement element) => element.remove()); _labelPartElements.clear();

flutter-zl · 2025-06-27T06:10:11Z

@chunhtai and I had the following conversation.

@chunhtai : for this pr, what is the difference between between using aria-labelledby with spans of strings vs concatenate them and assign to aria-label?

@flutter-zl : the major advantage i can think of is aria-labelledby programmatically concatenate strings. developers need to manually aria-label concatenate strings which may raise error.
For example developers may forget to add spacing between $firstName $lastName.
labelParts: [’$firstName, $lastName’]
aria-label=’$firstName $lastName’

@chunhtai : if so, sounds like we can just provide a utility in dart side so they can use before setting the Semantics.label?
if we have to provide an API like this, we can also just concatenate in the dart side and the web engine doesn't need to change

Hi @yjbanov, what is your opinion since you already have the context of #162094?

yjbanov · 2025-06-27T20:10:43Z

Yeah, I was thinking about some method of concatenation outside the Semantics widget itself (see #162094 (comment)). An alternative method could be for label to accept String | List<String>, but unfortunately Dart doesn't support union types, so this is not expressible. labelParts is kind of an emulation of union types, but it kind of complicates the API a little. We already have label + attributedLabel. Now we'd have label + attributedLabel + labelParts. Later we may have to also add attributedLabelParts? :)

Maybe what we need is a LabelBuilder class that incapsulates label and attributes, supporting concatenation of multiple labels. Strawman interface for such a class could be:

final class SemanticsLabelBuilder {
  void addPart(String label);
  void addAttributedPart(AttributedString label);
  SemanticsLabel build();
}

final class SemanticsLabel {
  /// The concatenation of labels made of parts supplied using `addPart` and `addAttributedPart` invocations.
  String get label;

  /// The attributed concatenation of labels made of parts supplied using `addPart` and `addAttributedPart` invocations.
  ///
  /// Returns null if no attributed parts were supplied in `SemanticsLabelBuilder`.
  AttributedString? get attributedLabel;
}

Sample usage:

// Plain label concatenation
var builder = SemanticsLabelBuilder()
  ..addPart('hello')
  ..addPart('world');
var label = builder build;
label.label; // returns 'hello world'
label.attributedLabel; // returns null

// Plain label concatenation
var builder = SemanticsLabelBuilder()
  ..addPart('hello')
  ..addAttributedPart(AttributedString('world', attributes = [LocaleStringAttribute(...)]));
var label = builder build;
label.label; // returns 'hello world' (loses attributes, but otherwise correct)
label.attributedLabel; // returns AttributedString with concatenated label and
                       // string attributes with adjusted text ranges, because text ranges
                       // can shift due to concatenation

chunhtai · 2025-06-27T20:24:48Z

I also prefer having concatenation outside of semantics system, adding a property is costly to all embeddings.

flutter-zl · 2025-07-08T06:19:04Z

I created a new PR(#171683) based on the feedback in #171040 (comment) and #171040 (comment).

## Description Please check comment: #171040 (comment). This PR adds `SemanticsLabelBuilder`, a new utility class for creating accessible concatenated labels with proper text direction handling and spacing. Currently, developers manually concatenate semantic labels using string interpolation, which is error-prone and leads to accessibility issues like missing spaces, incorrect text direction for RTL languages. The new builder provides automatic spacing, Unicode bidirectional text embedding for mixed LTR/RTL content. ### Before (error-prone manual concatenation): ```dart // Missing space String label = "$firstName$lastName"; // "JohnDoe" String englishText = "Welcome"; String arabicText = "مرحبا"; // Arabic "Hello" // Manual Concatenation (WITHOUT Unicode embedding): aria-label="Welcome 欢迎 مرحبا स्वागत है to our global app" // Problem: Arabic does not have proper text direction handling ``` ### After (automatic and accessible): Demo app after the change: https://label-0702.web.app/ ```dart // Automatic spacing and text direction handling final label = (SemanticsLabelBuilder() ..addPart(firstName) ..addPart(lastName)).build(); // Result: "John Doe" with proper aria-label generation // SemanticsLabelBuilder (WITH Unicode embedding): aria-label="Welcome 欢迎 [U+202B]مرحبا[U+202C] स्वागत है to our global app" // Result: Arabic has proper text direction handling ``` ## Issues Fixed This fixes #162094. This PR addresses the general accessibility problem of error-prone manual label concatenation that affects screen reader users. While not fixing a specific filed issue, it provides a robust solution for the common pattern of building complex semantic labels that are critical for accessibility compliance, particularly for multilingual applications and complex UI components like contact cards, dashboards, and e-commerce listings. ## Breaking Changes No breaking changes were made. This is a purely additive API that doesn't modify existing behavior or require any migration. ## Key Features Added - **SemanticsLabelBuilder**: Main builder class for concatenating text parts - **Automatic spacing**: Configurable separators with intelligent empty part handling - **Text direction support**: Unicode bidirectional embedding for RTL/LTR mixed content ## Example Usage ```dart // Basic usage final label = (SemanticsLabelBuilder() ..addPart('Contact') ..addPart('John Doe') ..addPart('Phone: +1-555-0123')).build(); // Result: "Contact John Doe Phone: +1-555-0123" // Custom separator final label = (SemanticsLabelBuilder(separator: ', ') ..addPart('Name: Alice') ..addPart('Status: Online')).build(); // Result: "Name: Alice, Status: Online" // Multilingual support final label = (SemanticsLabelBuilder(textDirection: TextDirection.ltr) ..addPart('Welcome', textDirection: TextDirection.ltr) ..addPart('مرحبا', textDirection: TextDirection.rtl) ..addPart('to our app')).build(); // Result: "Welcome ‫مرحبا‬ to our app" (with proper RTL embedding) ``` ``` ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. --------- Co-authored-by: Mouad Debbar <[email protected]>

…#171683) ## Description Please check comment: flutter#171040 (comment). This PR adds `SemanticsLabelBuilder`, a new utility class for creating accessible concatenated labels with proper text direction handling and spacing. Currently, developers manually concatenate semantic labels using string interpolation, which is error-prone and leads to accessibility issues like missing spaces, incorrect text direction for RTL languages. The new builder provides automatic spacing, Unicode bidirectional text embedding for mixed LTR/RTL content. ### Before (error-prone manual concatenation): ```dart // Missing space String label = "$firstName$lastName"; // "JohnDoe" String englishText = "Welcome"; String arabicText = "مرحبا"; // Arabic "Hello" // Manual Concatenation (WITHOUT Unicode embedding): aria-label="Welcome 欢迎 مرحبا स्वागत है to our global app" // Problem: Arabic does not have proper text direction handling ``` ### After (automatic and accessible): Demo app after the change: https://label-0702.web.app/ ```dart // Automatic spacing and text direction handling final label = (SemanticsLabelBuilder() ..addPart(firstName) ..addPart(lastName)).build(); // Result: "John Doe" with proper aria-label generation // SemanticsLabelBuilder (WITH Unicode embedding): aria-label="Welcome 欢迎 [U+202B]مرحبا[U+202C] स्वागत है to our global app" // Result: Arabic has proper text direction handling ``` ## Issues Fixed This fixes flutter#162094. This PR addresses the general accessibility problem of error-prone manual label concatenation that affects screen reader users. While not fixing a specific filed issue, it provides a robust solution for the common pattern of building complex semantic labels that are critical for accessibility compliance, particularly for multilingual applications and complex UI components like contact cards, dashboards, and e-commerce listings. ## Breaking Changes No breaking changes were made. This is a purely additive API that doesn't modify existing behavior or require any migration. ## Key Features Added - **SemanticsLabelBuilder**: Main builder class for concatenating text parts - **Automatic spacing**: Configurable separators with intelligent empty part handling - **Text direction support**: Unicode bidirectional embedding for RTL/LTR mixed content ## Example Usage ```dart // Basic usage final label = (SemanticsLabelBuilder() ..addPart('Contact') ..addPart('John Doe') ..addPart('Phone: +1-555-0123')).build(); // Result: "Contact John Doe Phone: +1-555-0123" // Custom separator final label = (SemanticsLabelBuilder(separator: ', ') ..addPart('Name: Alice') ..addPart('Status: Online')).build(); // Result: "Name: Alice, Status: Online" // Multilingual support final label = (SemanticsLabelBuilder(textDirection: TextDirection.ltr) ..addPart('Welcome', textDirection: TextDirection.ltr) ..addPart('مرحبا', textDirection: TextDirection.rtl) ..addPart('to our app')).build(); // Result: "Welcome ‫مرحبا‬ to our app" (with proper RTL embedding) ``` ``` ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. --------- Co-authored-by: Mouad Debbar <[email protected]>

flutter-zl added 5 commits June 17, 2025 22:22

add aria-labelledby

f45e337

add labelledby support for text_field

ce592e7

feat: Add aria-labelledby support for Flutter Web accessibility

d6a6b70

format styles

57286d1

Merge branch 'master' into feature/aria-labelledby-support

5aa0d7a

flutter-zl added 3 commits June 23, 2025 15:22

Merge branch 'master' into feature/aria-labelledby-support

72fdf3a

remove redudant code

0f9e7d3

Merge branch 'master' into feature/aria-labelledby-support

c52fff5

flutter-zl marked this pull request as ready for review June 24, 2025 16:52

flutter-zl requested review from chunhtai and mdebbar June 24, 2025 16:52

Merge branch 'master' into feature/aria-labelledby-support

af4ea56

mdebbar approved these changes Jun 26, 2025

View reviewed changes

flutter-zl closed this Jul 2, 2025

flutter-zl mentioned this pull request Jul 7, 2025

Add SemanticsLabelBuilder for Accessible Label Concatenation #171683

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feature/aria labelledby support#171040

Feature/aria labelledby support#171040
flutter-zl wants to merge 9 commits intoflutter:masterfrom
flutter-zl:feature/aria-labelledby-support

flutter-zl commented Jun 23, 2025 •

edited

Loading

Uh oh!

mdebbar left a comment

Uh oh!

mdebbar Jun 26, 2025

Uh oh!

mdebbar Jun 26, 2025

Uh oh!

mdebbar Jun 26, 2025

Uh oh!

mdebbar Jun 26, 2025

Uh oh!

flutter-zl commented Jun 27, 2025

Uh oh!

yjbanov commented Jun 27, 2025

Uh oh!

chunhtai commented Jun 27, 2025 •

edited

Loading

Uh oh!

flutter-zl commented Jul 8, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		final String oldLabelId = '$idPrefix-${semanticsObject.id}-$i';
		containerElement.querySelector('#$oldLabelId')?.remove();

Conversation

flutter-zl commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Problem Solved

Test 1: Customer Name + Required Field (2 parts)

Test 2: Email + Format Instructions + Required (3 parts)

Test 3: Submit Button + Keyboard Shortcut (Group semantics)

Test 4: Complex Password Instructions (4 parts)

Test 5: Single Label Comparison (Falls back to aria-label)

Pre-launch Checklist

Uh oh!

mdebbar left a comment

Choose a reason for hiding this comment

Uh oh!

mdebbar Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

mdebbar Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

mdebbar Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

mdebbar Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

flutter-zl commented Jun 27, 2025

Uh oh!

yjbanov commented Jun 27, 2025

Uh oh!

chunhtai commented Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

flutter-zl commented Jul 8, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

flutter-zl commented Jun 23, 2025 •

edited

Loading

chunhtai commented Jun 27, 2025 •

edited

Loading