Update predictive back docs by jesskuras · Pull Request #13640 · flutter/website

jesskuras · 2026-07-28T22:43:57Z

Summary

Updates documentation across the site to reflect the current state of Android predictive back support (Android 14+ default enablement) and recent API migrations:

Primary Predictive Back Guide (platform-integration/android/predictive-back.md): Updated support status, documented Android manifest setup (enableOnBackInvokedCallback="true"), and added a usage example for PopScope with onPopInvokedWithResult(bool didPop, Object? result).
Breaking Changes Guide (release/breaking-changes/android-predictive-back.md): Updated code snippets from onPopInvoked to onPopInvokedWithResult and refactored the setup section to delegate to the primary predictive back guide to avoid duplication.
Navigation Index (ui/navigation/index.md): Replaced deprecated WillPopScope references with PopScope.
Add-to-App Android Fragment Docs (add-to-app/android/add-flutter-fragment.md): Added documentation and Kotlin/Java examples for configuring shouldAutomaticallyHandleOnBackPressed(true).

Staged pages

gemini-code-assist

Code Review

This pull request updates the documentation for Android predictive back gesture support in Flutter, including instructions for FlutterFragment, PopScope migration, and related breaking changes. A typo was found in the breaking changes document where 'WithResult' was duplicated in a section header.

flutter-website-bot · 2026-07-28T22:52:34Z

Staged preview of the updated docs.flutter.dev site (updated for commit fc35846):

https://flutter-docs-prod--docs-pr13640-update-predictive-back-3ae2ylff.web.app

flutter-website-bot · 2026-07-28T22:58:35Z

Staged preview of the updated flutter.dev site (updated for commit fc35846):

https://flutter-dev-230821--www-pr13640-update-predictive-back-tmpj9jhe.web.app

…tive-back.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

justinmc

Just one clarification below, otherwise looks good.

justinmc · 2026-07-30T22:12:36Z

+To support predictive back gestures in your Flutter application on
+Android 13+:


Android 16 and above now sets enableOnBackInvokedCallback to true by default, so this step is only required on 13-15.

Then these steps don't hurt for Android 16+ then either, right? It'd be nice to avoid making this conditional, since I guess many Android app developers want to support versions before 16 at this point anyway.

parlough

Thanks for tackling this @jesskuras!

Some suggestions and notes to consider. Feel free to take or leave them.

parlough · 2026-07-30T22:32:26Z

 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`.


Suggested change

listen to pops by using `onPopInvokedWithResult`.

parlough · 2026-07-30T22:32:50Z

 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.


Suggested change

`onPopInvokedWithResult` is called after the pop is finished being handled.

parlough · 2026-07-30T22:33:12Z

 ```

 For cases where it's necessary to be notified that a
 pop was attempted, the `onPopInvoked` method can be


Suggested change

pop was attempted, the `onPopInvokedWithResult` method can be

parlough · 2026-07-30T22:33:50Z

-     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


Love redirecting to the primary doc rather than trying to repeat this and keep it updated. Thanks!

parlough · 2026-07-30T22:34:34Z

 )
 ```

 ### Migrating from Form.onWillPop to Form.canPop and Form.onPopInvoked


Suggested change

### Migrating from Form.onWillPop to Form.canPop and Form.onPopInvokedWithResult

parlough · 2026-07-30T23:19:28Z

+* `result`: An optional return payload passed when popping the route
+  (for example, via `Navigator.pop(context, result)`).


https://developers.google.com/style/word-list#via

Suggested change

* `result`: An optional return payload passed when popping the route

(for example, via `Navigator.pop(context, result)`).

* `result`: An optional return payload passed when popping the route,

for example, with `Navigator.pop(context, result)`.

parlough · 2026-07-30T23:22:08Z

+```

-[Android predictive back]: /release/breaking-changes/android-predictive-back
+For more details on API migrations, check out the


Consider placing this in its own section as it seems separate from the proceeding example.

Suggested change

For more details on API migrations, check out the

## More information

For more details on API migrations, check out the

parlough · 2026-07-30T23:22:55Z

+## 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


Consider linking the first use of PopScope to its API docs: https://api.flutter.dev/flutter/widgets/PopScope-class.html

parlough · 2026-07-30T23:23:32Z

+  (for example, via `Navigator.pop(context, result)`).

-* [Android predictive back][] breaking change
+### Example: Intercepting back navigation


I like the addition of an example!

parlough · 2026-07-30T23:24:14Z

 ```dart
 return PopScope(
  canPop: false,
  onPopInvoked: (bool didPop) async {


Suggested change

onPopInvokedWithResult: (bool didPop, Object? result) async {

jesskuras added 4 commits July 28, 2026 21:55

docs: update Android predictive back and PopScope APIs (flutter#13604)

9f2153e

docs: use 'check out' phrasing for references

3cddd1a

docs: integrate link phrasing into sentence

b1442f1

docs: refine predictive back wording and link phrasing

fe9783a

jesskuras requested a review from parlough July 28, 2026 22:43

jesskuras requested review from a team and sfshaza2 as code owners July 28, 2026 22:43

gemini-code-assist Bot reviewed Jul 28, 2026

View reviewed changes

Comment thread sites/docs/src/content/release/breaking-changes/android-predictive-back.md Outdated

parlough requested a review from justinmc July 28, 2026 23:03

jesskuras and others added 2 commits July 30, 2026 15:02

Merge branch 'main' into update-predictive-back-docs

0ad919b

Update sites/docs/src/content/release/breaking-changes/android-predic…

fc35846

…tive-back.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

justinmc reviewed Jul 30, 2026

View reviewed changes

parlough approved these changes Jul 30, 2026

View reviewed changes

parlough assigned jesskuras Jul 30, 2026

		To support predictive back gestures in your Flutter application on
		Android 13+:


	`onPopInvokedWithResult` is called after the pop is finished being handled.


	pop was attempted, the `onPopInvokedWithResult` method can be


	### Migrating from Form.onWillPop to Form.canPop and Form.onPopInvokedWithResult

		* `result`: An optional return payload passed when popping the route
		(for example, via `Navigator.pop(context, result)`).


	onPopInvokedWithResult: (bool didPop, Object? result) async {

Uh oh!

Conversation

jesskuras commented Jul 28, 2026 • edited by parlough Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Staged pages

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

flutter-website-bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

flutter-website-bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

justinmc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

parlough left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jesskuras commented Jul 28, 2026 •

edited by parlough

Loading

flutter-website-bot commented Jul 28, 2026 •

edited

Loading

flutter-website-bot commented Jul 28, 2026 •

edited

Loading