[`CupertinoThemeData.brightness`] is now nullable.
Original behavior
`CupertinoThemeData.brightness` is now used to override `MediaQuery.platformBrightness` for Cupertino widgets. Before this change, the `CupertinoThemeData.brightness` getter returned `Brightness.light` when it was set to null.
New behavior
Previously `CupertinoThemeData.brightness` was implemented as a getter:
- Who is affected
- Applications and packages relying on the previous behaviour or signature. Code that uses CupertinoThemeData.brightness, MediaQuery.platformBrightness, Brightness.light 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.
Official migration guide (excerpt, © The Flutter Authors, CC BY 3.0)
Generally [CupertinoThemeData.brightness][]
is rarely useful outside of the Flutter framework.
To retrieve the brightness for Cupertino widgets,
now use [CupertinoTheme.brightnessOf][] instead.
With this change, it is now possible to override
CupertinoThemeData.brightness in a CupertinoThemeData
subclass to change the brightness override. For example:
class AlwaysDarkCupertinoThemeData extends CupertinoThemeData {
Brightness brightness => Brightness.dark;
}When a CupertinoTheme uses the above CupertinoThemeData,
dark mode is enabled for all its Cupertino descendants
that are affected by this CupertinoTheme.
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
- Issue 47255
- Let material ThemeData dictate brightness if cupertinoOverrideTheme.brightness is null
- 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.