Add semantics role for form #170709

hannah-hyj · 2025-06-16T22:53:44Z

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.

chunhtai · 2025-06-17T18:32:08Z

packages/flutter/lib/src/widgets/form.dart

-      onWillPop: widget.onWillPop,
-      child: _FormScope(formState: this, generation: _generation, child: widget.child),
-    );
+    return Semantics(role: SemanticsRole.form, child: form);


This may need container: true so that it won't merge up and accidentally get other children to be included in the form

e.g something like this may break without the container:true here

Semantics(container:true, child: Column( children: [Semantics(container: true, child: Text('1')), Form(...)] ))

you will se that text('1') somehow become a child in the form in the semantics tree

chunhtai · 2025-06-17T18:36:07Z

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

+        semanticsObject,
+        preferredLabelRepresentation: LabelRepresentation.ariaLabel,
+      ) {
+    setAriaRole('form');


I vaguely remember web use the <form> tag to denote a form, and it is already used somewhere but for other purpose, cc @mdebbar , can you take a look to see if this is ok

I tested using VoiceOver on mac and it does work using ariaRole.

however, https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/form_role also has a warning "Warning: Use an HTML <form> element to contain your form controls, rather than the ARIA form role, unless you have a very good reason. The HTML <form> element is sufficient to tell assistive technologies that there is a form."

@mdebbar do we need to use the form tag or an ariaRole is good enough, wdyt?

"Warning: Use an HTML <form> element to contain your form controls, rather than the ARIA form role, unless you have a very good reason. The HTML <form> element is sufficient to tell assistive technologies that there is a form."

Do we have a "very good reason" to not use the <form> element? 🙂

In the SemanticForm class you could override the createElement method to make it return a <form> element instead of the default. Example:

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

Lines 19 to 24 in 12e4a89

@override

DomElement createElement() {

final DomElement element = domDocument.createElement('a');

element.style.display = 'block';

return element;

}

I vaguely remember web use the <form> tag to denote a form, and it is already used somewhere but for other purpose, cc @mdebbar , can you take a look to see if this is ok

We do use a form for autofill. But AFAICT, that behavior is disabled when semantics are on:

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

Line 168 in 12e4a89

void placeForm() {}

Thank you! updated to use the <form> element !

mdebbar · 2025-06-24T17:49:21Z

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

+        semanticsObject,
+        preferredLabelRepresentation: LabelRepresentation.ariaLabel,
+      ) {
+    setAriaRole('form');


"Warning: Use an HTML <form> element to contain your form controls, rather than the ARIA form role, unless you have a very good reason. The HTML <form> element is sufficient to tell assistive technologies that there is a form."

Do we have a "very good reason" to not use the <form> element? 🙂

In the SemanticForm class you could override the createElement method to make it return a <form> element instead of the default. Example:

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

Lines 19 to 24 in 12e4a89

@override

DomElement createElement() {

final DomElement element = domDocument.createElement('a');

element.style.display = 'block';

return element;

}

I vaguely remember web use the <form> tag to denote a form, and it is already used somewhere but for other purpose, cc @mdebbar , can you take a look to see if this is ok

We do use a form for autofill. But AFAICT, that behavior is disabled when semantics are on:

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

Line 168 in 12e4a89

void placeForm() {}

mdebbar · 2025-06-24T17:55:04Z

engine/src/flutter/lib/web_ui/test/engine/semantics/semantics_test.dart

  semantics().semanticsEnabled = false;
 }

+void _testForms() {


It would be nice to also have a test for this in _testSemanticRole above. Something that checks for:

tester.expectSemantics(''' <sem id="flt-semantic-node-0"> <form id="flt-semantic-node-1"> <sem id="flt-semantic-node-2"> <input /> </sem> </form> </sem>''');

updated tests, thanks!

mdebbar

LGTM if the framework changes LGT @chunhtai

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

chunhtai

LGTM

packages/flutter/lib/src/widgets/form.dart

Update semantics_test.dart Update licenses_flutter Update packages/flutter/lib/src/widgets/form.dart Update form.dart Update engine/src/flutter/lib/web_ui/lib/src/engine/semantics/form.dart Update engine/src/flutter/lib/web_ui/lib/src/engine/semantics/form.dart Update form.dart Update form.dart add tests lint Add form role Co-Authored-By: chunhtai <47866232+chunhtai@users.noreply.github.com> Co-Authored-By: Mouad Debbar <mouad.debbar@gmail.com>

fix: [flutter#161628](flutter#161628) ## 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].  [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md Co-authored-by: chunhtai <47866232+chunhtai@users.noreply.github.com> Co-authored-by: Mouad Debbar <mouad.debbar@gmail.com>

hannah-hyj requested a review from chunhtai June 16, 2025 22:53

github-actions bot added framework flutter/packages/flutter repository. See also f: labels. engine flutter/engine related. See also e: labels. a: accessibility Accessibility, e.g. VoiceOver or TalkBack. (aka a11y) platform-web Web applications specifically labels Jun 16, 2025

chunhtai reviewed Jun 17, 2025

View reviewed changes

hannah-hyj requested a review from mdebbar June 23, 2025 18:03

mdebbar reviewed Jun 24, 2025

View reviewed changes

hannah-hyj requested review from chunhtai and mdebbar June 25, 2025 20:28

hannah-hyj force-pushed the formrole branch from 0d65d68 to 0562c0f Compare June 25, 2025 20:30

mdebbar approved these changes Jun 25, 2025

View reviewed changes

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/form.dart Outdated Show resolved Hide resolved

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/form.dart Outdated Show resolved Hide resolved

hannah-hyj force-pushed the formrole branch from 9508a9e to 50a7331 Compare June 26, 2025 20:18

chunhtai approved these changes Jun 30, 2025

View reviewed changes

packages/flutter/lib/src/widgets/form.dart Outdated Show resolved Hide resolved

hannah-hyj force-pushed the formrole branch from 32b0b7c to 313c351 Compare June 30, 2025 20:45

hannah-hyj force-pushed the formrole branch from 6be3d4a to 395d91b Compare July 4, 2025 05:29

hannah-hyj added the autosubmit Merge PR when tree becomes green via auto submit App label Jul 4, 2025

auto-submit bot added this pull request to the merge queue Jul 4, 2025

Merged via the queue into flutter:master with commit 8edb61a Jul 4, 2025
175 checks passed

flutter-dashboard bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jul 4, 2025

engine-flutter-autoroll mentioned this pull request Jul 4, 2025

Roll Flutter from 2773c0c8e15e to 07073e911dd9 (141 revisions) flutter/packages#9558

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jul 4, 2025

8edb61a Add semantics role for form (flutter/flutter#170709)

0f7db27

engine-flutter-autoroll mentioned this pull request Jul 4, 2025

Roll Flutter from 2773c0c8e15e to 7d5f2e902a2b (142 revisions) flutter/packages#9559

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jul 4, 2025

8edb61a Add semantics role for form (flutter/flutter#170709)

182191b

engine-flutter-autoroll mentioned this pull request Jul 4, 2025

Roll Flutter from 2773c0c8e15e to bcab634d60c8 (143 revisions) flutter/packages#9560

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jul 4, 2025

8edb61a Add semantics role for form (flutter/flutter#170709)

c5d60e7

engine-flutter-autoroll mentioned this pull request Jul 5, 2025

Roll Flutter from 2773c0c8e15e to 03ef1ba910ca (147 revisions) flutter/packages#9561

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jul 5, 2025

8edb61a Add semantics role for form (flutter/flutter#170709)

eb4a413

engine-flutter-autoroll mentioned this pull request Jul 5, 2025

Roll Flutter from 2773c0c8e15e to 03ef1ba910ca (147 revisions) flutter/packages#9562

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jul 5, 2025

8edb61a Add semantics role for form (flutter/flutter#170709)

04bdb34

engine-flutter-autoroll mentioned this pull request Jul 6, 2025

Roll Flutter from 2773c0c8e15e to 10cde0d157cb (148 revisions) flutter/packages#9563

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jul 6, 2025

8edb61a Add semantics role for form (flutter/flutter#170709)

246e618

engine-flutter-autoroll mentioned this pull request Jul 6, 2025

Roll Flutter from 2773c0c8e15e to 160f2cbed84d (149 revisions) flutter/packages#9564

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jul 6, 2025

8edb61a Add semantics role for form (flutter/flutter#170709)

f697172

engine-flutter-autoroll mentioned this pull request Jul 6, 2025

Roll Flutter from 2773c0c8e15e to 160f2cbed84d (149 revisions) flutter/packages#9565

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jul 6, 2025

8edb61a Add semantics role for form (flutter/flutter#170709)

e50ea4e

engine-flutter-autoroll mentioned this pull request Jul 7, 2025

Roll Flutter from 2773c0c8e15e to d35bde5363d5 (152 revisions) flutter/packages#9573

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jul 7, 2025

8edb61a Add semantics role for form (flutter/flutter#170709)

5690d21

engine-flutter-autoroll mentioned this pull request Jul 7, 2025

Roll Flutter from 2773c0c8e15e to d35bde5363d5 (152 revisions) flutter/packages#9575

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jul 7, 2025

8edb61a Add semantics role for form (flutter/flutter#170709)

2c01bc1

engine-flutter-autoroll mentioned this pull request Jul 7, 2025

Roll Flutter from 2773c0c8e15e to a04fb324be73 (153 revisions) flutter/packages#9577

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jul 7, 2025

8edb61a Add semantics role for form (flutter/flutter#170709)

56c264f

Piinks mentioned this pull request Jul 19, 2025

Flutter Notable Commits - 2025 #161460

Open

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 14, 2025

8edb61a Add semantics role for form (flutter/flutter#170709)

ca5ce0c

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 14, 2025

8edb61a Add semantics role for form (flutter/flutter#170709)

3006ba2

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 15, 2025

8edb61a Add semantics role for form (flutter/flutter#170709)

8b95def

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 15, 2025

8edb61a Add semantics role for form (flutter/flutter#170709)

f3b7794

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 16, 2025

8edb61a Add semantics role for form (flutter/flutter#170709)

7f18467

	@override
	DomElement createElement() {
	final DomElement element = domDocument.createElement('a');
	element.style.display = 'block';
	return element;
	}

Add semantics role for form #170709

Add semantics role for form #170709

Uh oh!

Conversation

hannah-hyj commented Jun 16, 2025

Pre-launch Checklist

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!

hannah-hyj Jun 23, 2025 • edited by mdebbar Loading Uh oh! There was an error while loading. Please reload this page.

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!

Choose a reason for hiding this comment

Uh oh!

mdebbar left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

chunhtai left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

hannah-hyj Jun 23, 2025 •

edited by mdebbar

Loading