[Semantics] clarify Android header docs#183573
Merged
auto-submit[bot] merged 6 commits intoApr 8, 2026
Merged
Conversation
github-actions
Bot
added
framework
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request updates the documentation for SemanticsProperties.header to clarify its behavior on Android. The change explains that setting header: true is not sufficient on its own and that the headingLevel property must also be set to correctly mark a heading for Android accessibility services. It also includes a minor wording improvement for better clarity.
Comment on lines
+1804
to
+1807
| /// Support for this semantic varies by platform. Android accessibility | ||
| /// exposes headings rather than a separate header concept, so `header` alone | ||
| /// is not sufficient there. To mark content as a heading on Android, also set | ||
| /// [headingLevel]. |
Contributor
There was a problem hiding this comment.
To improve readability, consider rephrasing this paragraph. The current wording is a bit dense and could be more direct about why headingLevel is necessary on Android.
/// Support for this semantic varies by platform. On Android, this property
/// alone is not sufficient. To mark content as a heading for accessibility
/// services, also set [headingLevel]. This is because Android's accessibility
/// APIs expose headings, but not a separate header concept.References
- The style guide emphasizes optimizing for readability and providing useful documentation that explains the 'why' and 'how'. This suggestion aims to make the explanation clearer. (link)
Contributor
Author
|
Good call on readability. I pushed 84f728f6208 to simplify that paragraph and make the Android requirement for headingLevel more direct. |
Contributor
Author
|
Correction on the commit id in my previous note. The pushed commit is 9399c63. |
chunhtai
reviewed
Mar 18, 2026
| /// A header divides into sections. For example, an address book application | ||
| /// might define headers A, B, C, etc. to divide the list of alphabetically | ||
| /// sorted contacts into sections. | ||
| /// A header divides content into sections. For example, an address book |
Contributor
There was a problem hiding this comment.
The original doc is inaccurate, this paragraph describes heading, should move this to the heading property.
header is usually the top element of a page, for example, a title or app bar of a page.
| /// application might define headers A, B, C, etc. to divide the list of | ||
| /// alphabetically sorted contacts into sections. | ||
| /// | ||
| /// Support for this semantic varies by platform. On Android, this property |
Contributor
There was a problem hiding this comment.
this flag is not supported in Android, as Android don't have a notion of header in its assistive technologies
Contributor
Author
|
Thanks, this is helpful. I agree the docs are mixing header vs heading semantics right now. I’ll move the Android-specific heading guidance under and tighten the docs so they describe the top-of-page concept clearly. |
Contributor
Author
|
Follow-up (my last comment got formatting-mangled by CLI quoting): I’ll move the Android-specific guidance to headingLevel, and keep header docs focused on top-of-page/header semantics. |
Contributor
Author
|
Applied. I updated the docs so now describes top-of-page/section header semantics, and moved Android heading guidance to . Pushed in c4a172c. |
Contributor
Author
|
Follow-up to fix formatting in my previous comment: docs updated so header now describes top-of-page/section header semantics, and Android heading guidance now lives under headingLevel. Pushed in c4a172c. |
chunhtai
reviewed
Mar 19, 2026
| @@ -2232,6 +2226,9 @@ class SemanticsProperties extends DiagnosticableTree { | |||
| /// | |||
| /// On web, this sets the `aria-level` attribute (e.g., `aria-level="1"`). | |||
| /// On Android, this sets the `isHeading` property for accessibility. | |||
| /// | |||
| /// Android accessibility does not expose a separate "header" semantic, so | |||
Contributor
There was a problem hiding this comment.
this doesn't need to mention header, just move the old doc here. and we don't need to mention android here because this is supported for multiple platforms
/// A heading divides into sections. For example, an address book application
/// might define heading A, B, C, etc. to divide the list of alphabetically
/// sorted contacts into sections.
Contributor
Author
There was a problem hiding this comment.
Good call. I moved that section wording to headingLevel and removed the Android specific header note there. Updated in 421f2f0.
Contributor
|
Note to reviewers: this user appears to be running an unsupervised or poorly-supervised agent, and has received a warning and temporary ban. If interaction resumes next week, approach the review with caution. |
chunhtai
added
CICD
auto-submit
Bot
removed
the
autosubmit
Contributor
|
autosubmit label was removed for flutter/flutter/183573, because This PR has not met approval requirements for merging. The PR author is not a member of flutter-hackers and needs 1 more review(s) in order to merge this PR.
|
chunhtai
added
the
autosubmit
flutter-dashboard
Bot
removed
the
autosubmit
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Apr 8, 2026
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Apr 8, 2026
auto-submit Bot
pushed a commit
to flutter/packages
that referenced
this pull request
Apr 8, 2026
flutter/flutter@a0924c7...05e0ae0 2026-04-08 [email protected] Fix Android engine flags defaulting to true for malformed values (flutter/flutter#184631) 2026-04-08 [email protected] Try one more again (flutter/flutter#184767) 2026-04-08 [email protected] Remove custom `analysis_options.yaml` from `imitation_game_flutter` (flutter/flutter#184717) 2026-04-08 [email protected] Add more error handling to unawaited callsites (flutter/flutter#184526) 2026-04-08 [email protected] Refactor: remove material from absorb_ponter_test, container_test, lookup_boundary_test, page_view_test, router_test, semantics_clipping_test, semantics_merge_test, shadow_test, text_test (flutter/flutter#183309) 2026-04-08 [email protected] Remove editable_text_utils cross-imports from material and cupertino … (flutter/flutter#184519) 2026-04-08 [email protected] Replace hard coded max path length with system defined one. (flutter/flutter#184697) 2026-04-08 [email protected] [Re-land] Add Support For Built-in Kotlin (flutter/flutter#184745) 2026-04-08 [email protected] Manually stop and continue LLDB breakpoints on Xcode 26.4+ (flutter/flutter#184690) 2026-04-08 [email protected] Code freeze workflow (flutter/flutter#184246) 2026-04-08 [email protected] [Dot shorthands] Migrate examples/api/lib/widgets (flutter/flutter#183965) 2026-04-08 [email protected] [cupertino.dart] Implement CupertinoMenuAnchor and CupertinoMenuItem using RawMenuAnchor (flutter/flutter#182036) 2026-04-08 [email protected] [Semantics] clarify Android header docs (flutter/flutter#183573) 2026-04-08 [email protected] [ci] mac build_test bringup false (flutter/flutter#184738) 2026-04-08 [email protected] Reland "Apply rect clipping to surface views" (flutter/flutter#184732) 2026-04-08 [email protected] Remove bringup label for resharded Windows tool_integration_tests shards (flutter/flutter#184721) 2026-04-08 [email protected] Tool: Add search and filtering to widget preview scaffold (flutter/flutter#184023) 2026-04-08 [email protected] Update localization from translation console (flutter/flutter#184742) 2026-04-07 [email protected] Revert "Add Support For Built-in Kotlin (#184227)" (flutter/flutter#184739) 2026-04-07 [email protected] Collect HCPP adoption analytics for flutter run/build apk/build appbundle (flutter/flutter#184225) 2026-04-07 [email protected] Add a github workflow for reverting PRs. (flutter/flutter#184593) 2026-04-07 [email protected] Add Support For Built-in Kotlin (flutter/flutter#184227) 2026-04-07 [email protected] Revert "Apply rect clipping to surface views (#184471)" (flutter/flutter#184728) 2026-04-07 [email protected] [Fix-forward] Added Compose plugin to Add-to-app Integration Test (flutter/flutter#184681) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages Please CC [email protected],[email protected] on the revert to ensure that a human is aware of the problem. To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
mbcorona
pushed a commit
to mbcorona/flutter
that referenced
this pull request
Apr 15, 2026
Clarifies the `SemanticsProperties.header` API docs for Android. ## Issue The current documentation says that `header` marks a subtree as a header, but it does not explain that Android accessibility does not expose a separate header concept. In practice, `header: true` alone is not enough for TalkBack to treat the content as a heading on Android. This led to confusion in flutter#183111, where the behavior looked inconsistent across platforms even though the framework behavior is currently working as intended. ## What changed Updated the `SemanticsProperties.header` documentation to explain that: - Android accessibility exposes headings rather than a separate header concept - `header` alone is not sufficient on Android - callers should also set `headingLevel` when they want heading semantics on Android ## Outcome The API docs now describe the platform-specific behavior more accurately, so developers can understand why `header` behaves differently on Android and how to mark headings correctly there. Fixes flutter#183111 ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [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. ## Tests - `../../bin/dart analyze lib/src/semantics/semantics.dart` - `../../bin/flutter test test/widgets/semantics_test.dart --plain-name "Semantics widget supports all flags"` <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines [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/ [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md --------- Co-authored-by: chunhtai <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Clarifies the
SemanticsProperties.headerAPI docs for Android.Issue
The current documentation says that
headermarks a subtree as a header, but it does not explain that Android accessibility does not expose a separate header concept. In practice,header: truealone is not enough for TalkBack to treat the content as a heading on Android.This led to confusion in #183111, where the behavior looked inconsistent across platforms even though the framework behavior is currently working as intended.
What changed
Updated the
SemanticsProperties.headerdocumentation to explain that:headeralone is not sufficient on AndroidheadingLevelwhen they want heading semantics on AndroidOutcome
The API docs now describe the platform-specific behavior more accurately, so developers can understand why
headerbehaves differently on Android and how to mark headings correctly there.Fixes #183111
Pre-launch Checklist
///).Tests
../../bin/dart analyze lib/src/semantics/semantics.dart../../bin/flutter test test/widgets/semantics_test.dart --plain-name "Semantics widget supports all flags"