The `header` semantics property now behaves as a no-op on iOS and Android. To declare a section heading for accessibility purposes on these platforms, use the `headingLevel` property with a value greater than `0`.
Original behavior
Historically, Flutter used the boolean `header` semantics property to denote headings on platform implementations:
New behavior
Not stated in the source.
- Who is affected
- Applications and packages relying on the previous behaviour or signature. Code that uses UIAccessibilityTraitHeader, SliverAppBar, AppBar and related APIs.
- Practical impact
- Behaviour or API differences that can break builds or change runtime behaviour.
- What action should I take?
- Follow the official migration guide below, update affected call sites, run `dart fix --apply` where a fix is available, then run your tests.
Before and after (from the official guide)
| 1 | Semantics( | |
| 2 | − | header: true, |
| 3 | child: Text('Section Title'), | |
| 4 | ) |
| 1 | Semantics( | |
| 2 | + | headingLevel: 1, |
| 3 | child: Text('Section Title'), | |
| 4 | ) |
Raw before / after
Semantics(
header: true,
child: Text('Section Title'),
)Semantics(
headingLevel: 1,
child: Text('Section Title'),
)Official migration guide (excerpt, © The Flutter Authors, CC BY 3.0)
If your code previously used Semantics(header: true, ...) or
SemanticsProperties(header: true, ...) to declare headings,
migrate your code to use headingLevel: 1
(or another integer greater than 0).
Note that while setting headingLevel to any value greater than 0
declares a heading on Android and iOS, other platforms (such as the web)
treat the specific heading level number differently.
For example, on the web, values 1 through 6 map to the
corresponding <h1> through <h6> HTML elements.
Code before migration:
Semantics(
header: true,
child: Text('Section Title'),
)Code after migration:
Semantics(
headingLevel: 1,
child: Text('Section Title'),
)Similarly, if you used SemanticsProperties:
Code before migration:
SemanticsProperties(
header: true,
)Code after migration:
SemanticsProperties(
headingLevel: 1,
)AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.Listed in the official breaking-changes index (docs.flutter.dev/release/breaking-changes).
An official announcement or migration guide documents an intended behaviour or API change. A verified source change (git diff) shows code changed but does not by itself prove a public API is breaking. AI interpretations are labelled and never used to classify a change.
- Official migration guide
- Semantics
- SemanticsProperties
- SemanticsConfiguration
- Issue 175416
- PR 186916
- PR 175416
- Source commit
- b3045439b7c0
- Source last updated
- Oct 21, 2026
- Last synchronized
- Oct 21, 2026
- Publication status
- published
Publication history
- Oct 21, 2026, 8:31 PM: new → published (ingestion) — Backed by an official breaking-change/migration guide.
AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.