Update semantics header property that it isn't supported on Android. #183111

Activity

1. mbcorona

   added

   frameworkflutter/packages/flutter repository. See also f: labels.flutter/packages/flutter repository. See also f: labels.

   a: accessibilityAccessibility, e.g. VoiceOver or TalkBack. (aka a11y)Accessibility, e.g. VoiceOver or TalkBack. (aka a11y)

   platform-androidAndroid applications specificallyAndroid applications specifically

   d: api docsIssues with https://api.flutter.dev/Issues with https://api.flutter.dev/

   team-androidOwned by Android platform teamOwned by Android platform team

   on Mar 5, 2026
2. mbcorona commented on Mar 5, 2026

   

   mbcorona

   on Mar 5, 2026

   Member

   More actions

   Hi @fabianbrandscheid, thank you for reporting.

   Routing this to team-android to evaluate if this intentional change requires updated API documentation to clarify the cross-platform behavior.
3. stuartmorgan-g

   added

   fyi-androidFor the attention of Android platform teamFor the attention of Android platform team

   team-accessibilityOwned by Framework Accessibility team (i.e. responsible for accessibility code in flutter/flutter)Owned by Framework Accessibility team (i.e. responsible for accessibility code in flutter/flutter)

   and removed

   team-androidOwned by Android platform teamOwned by Android platform team

   on Mar 5, 2026
4. jesswrd

   added

   triaged-androidTriaged by Android platform teamTriaged by Android platform team

   on Mar 10, 2026
5. flutter-triage-bot

   removed

   fyi-androidFor the attention of Android platform teamFor the attention of Android platform team

   triaged-androidTriaged by Android platform teamTriaged by Android platform team

   on Mar 10, 2026
6. chunhtai commented on Mar 11, 2026

   

   chunhtai

   on Mar 11, 2026

   Contributor

   More actions

   Android doesn't have a header concept, they only have heading. In the past we mistakenly translate header:true into heading in android accessibility API. We later fixed the mistranslation.

   For the this issue, I think is WAI. However, I noticed our doc doesn't mention this https://api.flutter.dev/flutter/semantics/SemanticsProperties/header.html

   We should update the doc
7. chunhtai

   changed the title [-]The semantics header property should also work on Android.[/-] [+]Update semantics header property that it isn't supported on Android.[/+] on Mar 11, 2026
8. chunhtai

   added

   P3Issues that are less important to the Flutter projectIssues that are less important to the Flutter project

   triaged-accessibilityTriaged by Framework Accessibility teamTriaged by Framework Accessibility team

   on Mar 18, 2026
9. fabianbrandscheid commented on Mar 25, 2026

   

   fabianbrandscheid

   on Mar 25, 2026

   Author

   More actions

   @chunhtai At the moment, this means I have to set two properties in Flutter so that both platforms (Android and iOS) correctly expose the header/heading role of a text to the screen reader:

   Semantics(
     header: true,
     headingLevel: 1,
     child: Text(title),
   );
   

   This feels like a rather dirty workaround.
   Wouldn’t it be possible to provide a single header/heading flag that works consistently across both platforms?
10. github-merge-queue

    added a commit that references this issue on Apr 8, 2026

    [Semantics] clarify Android header docs (#183573)

    ...

    06d5086
11. auto-submit

    closed this as completedin #183573on Apr 8, 2026
12. mbcorona

    added a commit that references this issue on Apr 15, 2026

    [Semantics] clarify Android header docs (flutter#183573)

    ...

    b827009
13. github-actions commented on Apr 22, 2026

    

    github-actionsbot

    on Apr 22, 2026 – with GitHub Actions

    More actions

    This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of flutter doctor -v and a minimal reproduction of the issue.
14. github-actions

    locked as resolved and limited conversation to collaborators on Apr 22, 2026