A new `hidden` state was added to the `AppLifecycleState` enum to denote when the application is not visible.
Original behavior
The `AppLifecycleState` enum is used to indicate which lifecycle state the application is in when `WidgetsBindingObserver.didChangeAppLifecycleState` is called.
New behavior
The new state `AppLifecycleState.hidden` was added to the `AppLifecycleState` enum in the `dart:ui` package.
- Who is affected
- Applications and packages relying on the previous behaviour or signature. Code that uses AppLifecycleState, WidgetsBindingObserver.didChangeAppLifecycleState, AppLifecycleState.hidden.
- 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 | void didChangeAppLifecycleState(AppLifecycleState state) { | |
| 2 | switch (state) { | |
| 3 | case AppLifecycleState.resumed: | |
| 4 | case AppLifecycleState.inactive: | |
| 5 | // Do something when the app is visible... | |
| 6 | break; | |
| 7 | case AppLifecycleState.paused: | |
| 8 | case AppLifecycleState.detached: | |
| 9 | // Do something when the app is not visible... | |
| 10 | break; | |
| 11 | } | |
| 12 | } |
| 1 | void didChangeAppLifecycleState(AppLifecycleState state) { | |
| 2 | switch (state) { | |
| 3 | case AppLifecycleState.resumed: | |
| 4 | case AppLifecycleState.inactive: | |
| 5 | // Do something when the app is visible... | |
| 6 | break; | |
| 7 | + | case AppLifecycleState.hidden: // <-- This is the new state. |
| 8 | case AppLifecycleState.paused: | |
| 9 | case AppLifecycleState.detached: | |
| 10 | // Do something when the app is not visible... | |
| 11 | break; | |
| 12 | } | |
| 13 | } |
Raw before / after
void didChangeAppLifecycleState(AppLifecycleState state) {
switch (state) {
case AppLifecycleState.resumed:
case AppLifecycleState.inactive:
// Do something when the app is visible...
break;
case AppLifecycleState.paused:
case AppLifecycleState.detached:
// Do something when the app is not visible...
break;
}
}void didChangeAppLifecycleState(AppLifecycleState state) {
switch (state) {
case AppLifecycleState.resumed:
case AppLifecycleState.inactive:
// Do something when the app is visible...
break;
case AppLifecycleState.hidden: // <-- This is the new state.
case AppLifecycleState.paused:
case AppLifecycleState.detached:
// Do something when the app is not visible...
break;
}
}Official migration guide (excerpt, © The Flutter Authors, CC BY 3.0)
If code has switch statements that handle all cases of the AppLifecycleState
enum, a new case will need to be added to handle the AppLifecycleState.hidden
state.
Code before migration:
void didChangeAppLifecycleState(AppLifecycleState state) {
switch (state) {
case AppLifecycleState.resumed:
case AppLifecycleState.inactive:
// Do something when the app is visible...
break;
case AppLifecycleState.paused:
case AppLifecycleState.detached:
// Do something when the app is not visible...
break;
}
}Code after migration:
void didChangeAppLifecycleState(AppLifecycleState state) {
switch (state) {
case AppLifecycleState.resumed:
case AppLifecycleState.inactive:
// Do something when the app is visible...
break;
case AppLifecycleState.hidden: // <-- This is the new state.
case AppLifecycleState.paused:
case AppLifecycleState.detached:
// Do something when the app is not visible...
break;
}
}If there is already a default: case in the switch statement, or the code uses
conditionals instead, then the code will compile without changes, but the
default case or conditional will still need to be evaluated to decide if the
hidden state should also be handled.
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.
- 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.