From 9f2153edc5e917b4701dbe3dd9d3a3124cac9e5b Mon Sep 17 00:00:00 2001 From: Jess Kuras Date: Tue, 28 Jul 2026 21:55:25 +0000 Subject: [PATCH 1/8] docs: update Android predictive back and PopScope APIs (#13604) --- .../android/add-flutter-fragment.md | 30 ++++++ .../android/predictive-back.md | 100 ++++++++++-------- .../android-predictive-back.md | 32 ++---- sites/docs/src/content/ui/navigation/index.md | 6 +- 4 files changed, 103 insertions(+), 65 deletions(-) diff --git a/sites/docs/src/content/add-to-app/android/add-flutter-fragment.md b/sites/docs/src/content/add-to-app/android/add-flutter-fragment.md index ae7e280b4fa..82dd7ef153c 100644 --- a/sites/docs/src/content/add-to-app/android/add-flutter-fragment.md +++ b/sites/docs/src/content/add-to-app/android/add-flutter-fragment.md @@ -274,6 +274,36 @@ With the OS signals forwarded to Flutter, your `FlutterFragment` works as expected. You have now added a `FlutterFragment` to your existing Android app. +### Automatic back button and predictive back handling + +When embedding a `FlutterFragment` into a native Android app on Android 13 or +higher (API level 33+), you can configure the fragment to automatically handle +system back button presses and predictive back gestures without manually +forwarding `onBackPressed()`. + +Set `shouldAutomaticallyHandleOnBackPressed(true)` when building your fragment: + + + + +```kotlin +val flutterFragment = FlutterFragment.withNewEngine() + .shouldAutomaticallyHandleOnBackPressed(true) + .build() +``` + + + + +```java +FlutterFragment flutterFragment = FlutterFragment.withNewEngine() + .shouldAutomaticallyHandleOnBackPressed(true) + .build(); +``` + + + + The simplest integration path uses a new `FlutterEngine`, which comes with a non-trivial initialization time, leading to a blank UI until Flutter is diff --git a/sites/docs/src/content/platform-integration/android/predictive-back.md b/sites/docs/src/content/platform-integration/android/predictive-back.md index 11766c4fc9b..b22851ae5dc 100644 --- a/sites/docs/src/content/platform-integration/android/predictive-back.md +++ b/sites/docs/src/content/platform-integration/android/predictive-back.md @@ -2,60 +2,76 @@ title: Add the predictive-back gesture shortTitle: Predictive-back description: >- - Learn how to add the predictive back gesture to your Android app. + Learn how to enable and handle Android predictive back gestures in Flutter. --- -This feature has landed in Flutter, -but it's not enabled by default in Android itself yet. -You can try it out using the following instructions. +Android predictive back navigation lets users preview the animation of +swiping back to a previous screen or returning to the home screen before +releasing the gesture. -## Configure your app +## Overview -Make sure your app supports Android API 33 or higher, -as predictive back won't work on older versions of Android. -Then, set the flag `android:enableOnBackInvokedCallback="true"` -in `android/app/src/main/AndroidManifest.xml`. +Starting with Android 14 (API level 34), predictive back animations are +enabled by default for system gestures when supported by the application. +Flutter provides built-in support for predictive back animations across +default page route transitions and custom pop handling. -## Configure your device +## Enable predictive back in Android -You need to enable Developer Mode and set a flag on your device, -so you can't yet expect predictive back to work on most users' -Android devices. If you want to try it out on your own device though, -make sure it's running API 33 or higher, and then in -**Settings => System => Developer** options, -make sure the switch is enabled next to **Predictive back animations**. +To support predictive back gestures in your Flutter application on +Android 13+: -## Set up your app +1. Open `android/app/src/main/AndroidManifest.xml`. +2. Add `android:enableOnBackInvokedCallback="true"` to the `` tag: -The predictive back route transitions are currently -not enabled by default, so for now you'll need to enable them -manually in your app. -Typically, you do this by setting them in your theme: - -```dart -MaterialApp( - theme: ThemeData( - pageTransitionsTheme: const PageTransitionsTheme( - builders: { - // Set the predictive back transitions for Android. - TargetPlatform.android: PredictiveBackPageTransitionsBuilder(), - }, - ), - ), - ... -), +```xml + + + + + ``` -## Run your app +## Handle back gestures with PopScope + +To customize back navigation or prevent users from accidentally leaving a +screen, use the `PopScope` widget. `PopScope` replaces the deprecated +`WillPopScope` widget and works seamlessly with predictive back gestures. -Lastly, just make sure you're using at least -Flutter version 3.22.2 to run your app, -which is the latest stable release at the time of this writing. +### Callback parameters -## For more information +`PopScope` uses the `onPopInvokedWithResult` callback: -You can find more information at the following link: +* `didPop`: A boolean indicating whether the pop operation succeeded. If + `canPop` is `false`, `didPop` is `false`. +* `result`: An optional return payload passed when popping the route + (for example, via `Navigator.pop(context, result)`). -* [Android predictive back][] breaking change +### Example: Intercepting back navigation + +```dart +PopScope( + canPop: false, + onPopInvokedWithResult: (bool didPop, Object? result) async { + if (didPop) { + return; + } + final shouldLeave = await _showExitConfirmationDialog(context); + if (shouldLeave && context.mounted) { + Navigator.of(context).pop(result); + } + }, + child: Scaffold( + appBar: AppBar(title: const Text('Form Screen')), + body: const Center(child: Text('Complete the form before leaving.')), + ), +) +``` -[Android predictive back]: /release/breaking-changes/android-predictive-back +For more details on API migrations, see the +[Android predictive back migration guide]( +/release/breaking-changes/android-predictive-back). diff --git a/sites/docs/src/content/release/breaking-changes/android-predictive-back.md b/sites/docs/src/content/release/breaking-changes/android-predictive-back.md index bad12548756..87a621ec481 100644 --- a/sites/docs/src/content/release/breaking-changes/android-predictive-back.md +++ b/sites/docs/src/content/release/breaking-changes/android-predictive-back.md @@ -54,13 +54,13 @@ listen to pops by using `onPopInvoked`. ```dart PopScope( canPop: _myPopDisableEnableLogic(), - onPopInvoked: (bool didPop) { + onPopInvokedWithResult: (bool didPop, Object? result) { // Handle the pop. If `didPop` is false, it was blocked. }, ) ``` -### Form.canPop and Form.onPopInvoked +### Form.canPop and Form.onPopInvokedWithResultWithResult These two new parameters are based on `PopScope` and replace the deprecated `Form.onWillPop` parameter. They are used with `PopScope` in the same way as @@ -69,7 +69,7 @@ above. ```dart Form( canPop: _myPopDisableEnableLogic(), - onPopInvoked: (bool didPop) { + onPopInvokedWithResult: (bool didPop, Object? result) { // Handle the pop. If `didPop` is false, it was blocked. }, ) @@ -158,7 +158,7 @@ Code after migration: ```dart PopScope( canPop: true, - onPopInvoked: (bool didPop) { + onPopInvokedWithResult: (bool didPop, Object? result) { _myHandleOnPopMethod(); }, child: ... @@ -342,22 +342,10 @@ return PopScope( ### Supporting predictive back - 1. Run Android 14 (API level 34) or above. - 1. Enable the feature flag for predictive back on - the device under "Developer options". - This will be unnecessary on future versions of Android. - 1. Set `android:enableOnBackInvokedCallback="true"` in - `android/app/src/main/AndroidManifest.xml`. - If needed, refer to - [Android's full guide]({{site.android-dev}}/guide/navigation/custom-back/predictive-back-gesture). - for migrating Android apps to support predictive back. - 1. Make sure you're using version `3.14.0-7.0.pre` - of Flutter or greater. - 1. Make sure your Flutter app doesn't use the - `WillPopScope` widget. Using it disables - predictive back. If needed, use `PopScope` instead. - 1. Run the app and perform a back gesture (swipe from the - left side of the screen). +For complete setup instructions, guidelines on predictive back gesture +animations, and Android manifest configuration, see the primary guide: +[Add the predictive-back gesture]( +/platform-integration/android/predictive-back). ## Timeline @@ -372,7 +360,7 @@ API documentation: * [`NavigatorPopHandler`][] * [`PopEntry`][] * [`Form.canPop`][] -* [`Form.onPopInvoked`][] +* [`Form.onPopInvokedWithResult`][] * [`Route.popDisposition`][] * [`ModalRoute.registerPopEntry`][] * [`ModalRoute.unregisterPopEntry`][] @@ -390,7 +378,7 @@ Relevant PRs: [`NavigatorPopHandler`]: {{site.api}}/flutter/widgets/NavigatorPopHandler-class.html [`PopEntry`]: {{site.api}}/flutter/widgets/PopEntry-class.html [`Form.canPop`]: {{site.api}}/flutter/widgets/Form/canPop.html -[`Form.onPopInvoked`]: {{site.api}}/flutter/widgets/Form/onPopInvoked.html +[`Form.onPopInvokedWithResult`]: {{site.api}}/flutter/widgets/Form/onPopInvokedWithResult.html [`Route.popDisposition`]: {{site.api}}/flutter/widgets/Route/popDisposition.html [`ModalRoute.registerPopEntry`]: {{site.api}}/flutter/widgets/ModalRoute/registerPopEntry.html [`ModalRoute.unregisterPopEntry`]: {{site.api}}/flutter/widgets/ModalRoute/unregisterPopEntry.html diff --git a/sites/docs/src/content/ui/navigation/index.md b/sites/docs/src/content/ui/navigation/index.md index 9c58be6967a..5d18b4659a5 100644 --- a/sites/docs/src/content/ui/navigation/index.md +++ b/sites/docs/src/content/ui/navigation/index.md @@ -129,8 +129,12 @@ navigates by removing a _page-backed_ route from the Navigator, all _pageless_ routes after (up until the next _page-backed_ route) are removed too. :::note -You can't prevent navigation from page-backed screens using `WillPopScope`. +You can't prevent navigation from page-backed screens using `PopScope` +or the deprecated `WillPopScope`. Instead, you should consult your routing package's API documentation. +For information on migrating to `PopScope`, see the +[Android predictive back migration guide]( +/release/breaking-changes/android-predictive-back). ::: ## Web support From 3cddd1a98dc3013fd257cececfe6867a423de3f3 Mon Sep 17 00:00:00 2001 From: Jess Kuras Date: Tue, 28 Jul 2026 22:32:40 +0000 Subject: [PATCH 2/8] docs: use 'check out' phrasing for references --- .../src/content/platform-integration/android/predictive-back.md | 2 +- .../content/release/breaking-changes/android-predictive-back.md | 2 +- sites/docs/src/content/ui/navigation/index.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/sites/docs/src/content/platform-integration/android/predictive-back.md b/sites/docs/src/content/platform-integration/android/predictive-back.md index b22851ae5dc..50919e2552b 100644 --- a/sites/docs/src/content/platform-integration/android/predictive-back.md +++ b/sites/docs/src/content/platform-integration/android/predictive-back.md @@ -72,6 +72,6 @@ PopScope( ) ``` -For more details on API migrations, see the +For more details on API migrations, check out the [Android predictive back migration guide]( /release/breaking-changes/android-predictive-back). diff --git a/sites/docs/src/content/release/breaking-changes/android-predictive-back.md b/sites/docs/src/content/release/breaking-changes/android-predictive-back.md index 87a621ec481..f6270659f0e 100644 --- a/sites/docs/src/content/release/breaking-changes/android-predictive-back.md +++ b/sites/docs/src/content/release/breaking-changes/android-predictive-back.md @@ -343,7 +343,7 @@ return PopScope( ### Supporting predictive back For complete setup instructions, guidelines on predictive back gesture -animations, and Android manifest configuration, see the primary guide: +animations, and Android manifest configuration, check out the primary guide: [Add the predictive-back gesture]( /platform-integration/android/predictive-back). diff --git a/sites/docs/src/content/ui/navigation/index.md b/sites/docs/src/content/ui/navigation/index.md index 5d18b4659a5..b999e494b64 100644 --- a/sites/docs/src/content/ui/navigation/index.md +++ b/sites/docs/src/content/ui/navigation/index.md @@ -132,7 +132,7 @@ routes after (up until the next _page-backed_ route) are removed too. You can't prevent navigation from page-backed screens using `PopScope` or the deprecated `WillPopScope`. Instead, you should consult your routing package's API documentation. -For information on migrating to `PopScope`, see the +For more information on migrating to `PopScope`, check out the [Android predictive back migration guide]( /release/breaking-changes/android-predictive-back). ::: From b1442f121cebdebb410c51667780b784037722ff Mon Sep 17 00:00:00 2001 From: Jess Kuras Date: Tue, 28 Jul 2026 22:36:46 +0000 Subject: [PATCH 3/8] docs: integrate link phrasing into sentence --- .../release/breaking-changes/android-predictive-back.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/sites/docs/src/content/release/breaking-changes/android-predictive-back.md b/sites/docs/src/content/release/breaking-changes/android-predictive-back.md index f6270659f0e..f8e02800581 100644 --- a/sites/docs/src/content/release/breaking-changes/android-predictive-back.md +++ b/sites/docs/src/content/release/breaking-changes/android-predictive-back.md @@ -343,9 +343,8 @@ return PopScope( ### Supporting predictive back For complete setup instructions, guidelines on predictive back gesture -animations, and Android manifest configuration, check out the primary guide: -[Add the predictive-back gesture]( -/platform-integration/android/predictive-back). +animations, and Android manifest configuration, check out how to [add the +predictive-back gesture](/platform-integration/android/predictive-back). ## Timeline From fe9783aa244cedbe325faeaab53d8abae459fe70 Mon Sep 17 00:00:00 2001 From: Jess Kuras Date: Tue, 28 Jul 2026 22:42:58 +0000 Subject: [PATCH 4/8] docs: refine predictive back wording and link phrasing --- .../src/content/platform-integration/android/predictive-back.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sites/docs/src/content/platform-integration/android/predictive-back.md b/sites/docs/src/content/platform-integration/android/predictive-back.md index 50919e2552b..b486243d33a 100644 --- a/sites/docs/src/content/platform-integration/android/predictive-back.md +++ b/sites/docs/src/content/platform-integration/android/predictive-back.md @@ -40,7 +40,7 @@ Android 13+: To customize back navigation or prevent users from accidentally leaving a screen, use the `PopScope` widget. `PopScope` replaces the deprecated -`WillPopScope` widget and works seamlessly with predictive back gestures. +`WillPopScope` widget and supports predictive back gestures. ### Callback parameters From fc35846147d69811f99983651245e29f6de1a5e2 Mon Sep 17 00:00:00 2001 From: Jess K <49662805+jesskuras@users.noreply.github.com> Date: Thu, 30 Jul 2026 15:05:16 -0700 Subject: [PATCH 5/8] Update sites/docs/src/content/release/breaking-changes/android-predictive-back.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- .../content/release/breaking-changes/android-predictive-back.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sites/docs/src/content/release/breaking-changes/android-predictive-back.md b/sites/docs/src/content/release/breaking-changes/android-predictive-back.md index f8e02800581..04ba75b339e 100644 --- a/sites/docs/src/content/release/breaking-changes/android-predictive-back.md +++ b/sites/docs/src/content/release/breaking-changes/android-predictive-back.md @@ -60,7 +60,7 @@ PopScope( ) ``` -### Form.canPop and Form.onPopInvokedWithResultWithResult +### Form.canPop and Form.onPopInvokedWithResult These two new parameters are based on `PopScope` and replace the deprecated `Form.onWillPop` parameter. They are used with `PopScope` in the same way as From fbd12d73340a9cb33eafe4d5809ca2693c48e474 Mon Sep 17 00:00:00 2001 From: Jess Kuras Date: Fri, 31 Jul 2026 23:29:51 +0000 Subject: [PATCH 6/8] docs: address PR review feedback on predictive back and PopScope --- .../add-to-app/android/add-flutter-fragment.md | 3 ++- .../platform-integration/android/predictive-back.md | 10 +++++++--- .../breaking-changes/android-predictive-back.md | 12 ++++++------ 3 files changed, 15 insertions(+), 10 deletions(-) diff --git a/sites/docs/src/content/add-to-app/android/add-flutter-fragment.md b/sites/docs/src/content/add-to-app/android/add-flutter-fragment.md index 82dd7ef153c..fa5671d81be 100644 --- a/sites/docs/src/content/add-to-app/android/add-flutter-fragment.md +++ b/sites/docs/src/content/add-to-app/android/add-flutter-fragment.md @@ -281,7 +281,8 @@ higher (API level 33+), you can configure the fragment to automatically handle system back button presses and predictive back gestures without manually forwarding `onBackPressed()`. -Set `shouldAutomaticallyHandleOnBackPressed(true)` when building your fragment: +Instead of overriding `onBackPressed` as shown above, set +`shouldAutomaticallyHandleOnBackPressed(true)` when building your fragment: diff --git a/sites/docs/src/content/platform-integration/android/predictive-back.md b/sites/docs/src/content/platform-integration/android/predictive-back.md index b486243d33a..cb3e8c1cf66 100644 --- a/sites/docs/src/content/platform-integration/android/predictive-back.md +++ b/sites/docs/src/content/platform-integration/android/predictive-back.md @@ -39,8 +39,9 @@ Android 13+: ## Handle back gestures with PopScope To customize back navigation or prevent users from accidentally leaving a -screen, use the `PopScope` widget. `PopScope` replaces the deprecated -`WillPopScope` widget and supports predictive back gestures. +screen, use the [`PopScope`]({{site.api}}/flutter/widgets/PopScope-class.html) +widget. `PopScope` replaces the deprecated `WillPopScope` widget and +supports predictive back gestures. ### Callback parameters @@ -49,7 +50,7 @@ screen, use the `PopScope` widget. `PopScope` replaces the deprecated * `didPop`: A boolean indicating whether the pop operation succeeded. If `canPop` is `false`, `didPop` is `false`. * `result`: An optional return payload passed when popping the route - (for example, via `Navigator.pop(context, result)`). + (for example, with `Navigator.pop(context, result)`). ### Example: Intercepting back navigation @@ -72,6 +73,9 @@ PopScope( ) ``` +## More information + For more details on API migrations, check out the [Android predictive back migration guide]( /release/breaking-changes/android-predictive-back). + diff --git a/sites/docs/src/content/release/breaking-changes/android-predictive-back.md b/sites/docs/src/content/release/breaking-changes/android-predictive-back.md index 04ba75b339e..c2e41eff959 100644 --- a/sites/docs/src/content/release/breaking-changes/android-predictive-back.md +++ b/sites/docs/src/content/release/breaking-changes/android-predictive-back.md @@ -49,7 +49,7 @@ whether it was successful. The `PopScope` class directly replaces `WillPopScope` in order to enable predictive back. Instead of deciding whether a pop is possible at the time it occurs, this is set ahead of time with the `canPop` boolean. You can still -listen to pops by using `onPopInvoked`. +listen to pops by using `onPopInvokedWithResult`. ```dart PopScope( @@ -135,11 +135,11 @@ PopScope( ``` For cases where it's necessary to be notified that a -pop was attempted, the `onPopInvoked` method can be +pop was attempted, the `onPopInvokedWithResult` method can be used in a similar way to `onWillPop`. Keep in mind that while `onWillPop` was called before the pop was handled and had the ability to cancel it, -`onPopInvoked` is called after the pop is finished being handled. +`onPopInvokedWithResult` is called after the pop is finished being handled. Code before migration: @@ -197,12 +197,12 @@ NavigatorPopHandler( ) ``` -### Migrating from Form.onWillPop to Form.canPop and Form.onPopInvoked +### Migrating from Form.onWillPop to Form.canPop and Form.onPopInvokedWithResult Previously, `Form` used a `WillPopScope` instance under the hood and exposed its `onWillPop` method. This has been replaced with a `PopScope` that exposes its -`canPop` and `onPopInvoked` methods. +`canPop` and `onPopInvokedWithResult` methods. Migrating is identical to migrating from `WillPopScope` to `PopScope`, detailed above. @@ -326,7 +326,7 @@ Code after migration: ```dart return PopScope( canPop: false, - onPopInvoked: (bool didPop) async { + onPopInvokedWithResult: (bool didPop, Object? result) async { if (didPop) { return; } From a977aafdeedd69e2f1205b4416d2fbac2a787c27 Mon Sep 17 00:00:00 2001 From: Jess K <49662805+jesskuras@users.noreply.github.com> Date: Fri, 31 Jul 2026 17:01:26 -0700 Subject: [PATCH 7/8] Apply suggestions from code review Co-authored-by: Parker Lougheed --- .../android/predictive-back.md | 16 ++++++++-------- sites/docs/src/content/ui/navigation/index.md | 8 +++++--- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/sites/docs/src/content/platform-integration/android/predictive-back.md b/sites/docs/src/content/platform-integration/android/predictive-back.md index cb3e8c1cf66..fb7c7321cc6 100644 --- a/sites/docs/src/content/platform-integration/android/predictive-back.md +++ b/sites/docs/src/content/platform-integration/android/predictive-back.md @@ -5,9 +5,10 @@ description: >- Learn how to enable and handle Android predictive back gestures in Flutter. --- -Android predictive back navigation lets users preview the animation of -swiping back to a previous screen or returning to the home screen before -releasing the gesture. +The Android predictive back gesture lets users preview +where a back gesture will navigate to, +whether that's the previous screen or the home screen, +before they commit to or cancel it. ## Overview @@ -18,13 +19,12 @@ default page route transitions and custom pop handling. ## Enable predictive back in Android -To support predictive back gestures in your Flutter application on -Android 13+: +To support predictive back gestures in your Flutter app +on Android 13 or later: 1. Open `android/app/src/main/AndroidManifest.xml`. 2. Add `android:enableOnBackInvokedCallback="true"` to the `` tag: -```xml Date: Sat, 1 Aug 2026 00:09:33 +0000 Subject: [PATCH 8/8] docs: keep FlutterEngine integration summary with its parent section --- .../add-to-app/android/add-flutter-fragment.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/sites/docs/src/content/add-to-app/android/add-flutter-fragment.md b/sites/docs/src/content/add-to-app/android/add-flutter-fragment.md index fa5671d81be..fc678bd6bea 100644 --- a/sites/docs/src/content/add-to-app/android/add-flutter-fragment.md +++ b/sites/docs/src/content/add-to-app/android/add-flutter-fragment.md @@ -274,6 +274,14 @@ With the OS signals forwarded to Flutter, your `FlutterFragment` works as expected. You have now added a `FlutterFragment` to your existing Android app. +The simplest integration path uses a new `FlutterEngine`, +which comes with a non-trivial initialization time, +leading to a blank UI until Flutter is +initialized and rendered the first time. +Most of this time overhead can be avoided by using a cached, pre-warmed +`FlutterEngine`, which is discussed in +[Using a pre-warmed `FlutterEngine`](#using-a-pre-warmed-flutterengine). + ### Automatic back button and predictive back handling When embedding a `FlutterFragment` into a native Android app on Android 13 or @@ -305,13 +313,6 @@ FlutterFragment flutterFragment = FlutterFragment.withNewEngine() -The simplest integration path uses a new `FlutterEngine`, -which comes with a non-trivial initialization time, -leading to a blank UI until Flutter is -initialized and rendered the first time. -Most of this time overhead can be avoided by using -a cached, pre-warmed `FlutterEngine`, which is discussed next. - ## Using a pre-warmed `FlutterEngine` By default, a `FlutterFragment` creates its own instance