Skip to content

Clarify RouterDelegate popRoute bubbling#186875

Merged
auto-submit[bot] merged 2 commits into
flutter:masterfrom
mvincentong:docs-router-delegate-pop-route
Jun 4, 2026
Merged

Clarify RouterDelegate popRoute bubbling#186875
auto-submit[bot] merged 2 commits into
flutter:masterfrom
mvincentong:docs-router-delegate-pop-route

Conversation

@mvincentong

@mvincentong mvincentong commented May 21, 2026

Copy link
Copy Markdown
Contributor

Fixes #118975.

RouterDelegate.popRoute said returning false would cause the entire app to be popped, which skips an important nested-router detail. In a nested Router setup, returning false means this delegate did not handle the pop request, so the request can continue through a parent BackButtonDispatcher; only an unhandled request that reaches the root binding triggers the application pop behavior.

Verification:

  • ./bin/dart format packages/flutter/lib/src/widgets/router.dart
  • ./bin/flutter analyze packages/flutter/lib/src/widgets/router.dart
  • git diff --check

@github-actions github-actions Bot added framework flutter/packages/flutter repository. See also f: labels. f: routes Navigator, Router, and related APIs. labels May 21, 2026
gemini-code-assist[bot]
gemini-code-assist Bot reviewed May 21, 2026
View reviewed changes

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates the documentation for RouterDelegate.popRoute to clarify the behavior of its return values and the propagation of pop requests through nested routers. Feedback suggests refining the terminology to more accurately describe the platform's response to SystemNavigator.pop and using the term 'bubbling' to improve clarity regarding event propagation.

Comment thread packages/flutter/lib/src/widgets/router.dart Outdated
@mvincentong mvincentong force-pushed the docs-router-delegate-pop-route branch from 734c7c2 to 74bc85b Compare May 21, 2026 12:27
@mvincentong

mvincentong commented May 21, 2026

Copy link
Copy Markdown
Contributor Author

Addressed Gemini wording feedback in head 74bc85bb92: the docs now describe returning true as preventing the request from bubbling up and describe SystemNavigator.pop as requesting the platform to pop the application.

Verification rerun:

  • ./bin/dart format packages/flutter/lib/src/widgets/router.dart
  • ./bin/flutter analyze packages/flutter/lib/src/widgets/router.dart
  • git diff --check

@Piinks Piinks requested a review from justinmc May 26, 2026 22:27
justinmc
justinmc approved these changes Jun 4, 2026
View reviewed changes

@justinmc justinmc left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 👍 Looks perfect to me, thanks for making these docs better! You're right that they did not consider a nested navigation scenario.

@justinmc justinmc added the CICD Run CI/CD label Jun 4, 2026
@AbdeMohlbi AbdeMohlbi added the autosubmit Merge PR when tree becomes green via auto submit App label Jun 4, 2026
@auto-submit auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jun 4, 2026
@auto-submit

auto-submit Bot commented Jun 4, 2026

Copy link
Copy Markdown
Contributor

autosubmit label was removed for flutter/flutter/186875, because The base commit of the PR is older than 7 days and can not be merged. Please merge the latest changes from the main into this branch and resubmit the PR.

@github-actions github-actions Bot removed the CICD Run CI/CD label Jun 4, 2026
@AbdeMohlbi AbdeMohlbi added CICD Run CI/CD autosubmit Merge PR when tree becomes green via auto submit App labels Jun 4, 2026
@auto-submit auto-submit Bot added this pull request to the merge queue Jun 4, 2026
Merged via the queue into flutter:master with commit a1b0d22 Jun 4, 2026
94 checks passed
@flutter-dashboard flutter-dashboard Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jun 4, 2026
This was referenced Jun 5, 2026
Closed
Closed
Closed
Merged
auto-submit Bot pushed a commit to flutter/packages that referenced this pull request Jun 5, 2026
@engine-flutter-autoroll
Roll Flutter from 2ba5420a7049 to 1bdf4af29076 (43 revisions) (#11849)
13b49f4 
Roll Flutter from 2ba5420a7049 to 1bdf4af29076 (43 revisions)

flutter/flutter@2ba5420...1bdf4af

2026-06-05 engine-flutter-autoroll@skia.org Roll Packages from 03352b5 to 61bdbb4 (5 revisions) (flutter/flutter#187612)
2026-06-05 engine-flutter-autoroll@skia.org Roll Skia from 6e003d7f69c8 to a47a9a2c8ae5 (1 revision) (flutter/flutter#187610)
2026-06-05 engine-flutter-autoroll@skia.org Roll Dart SDK from aad8be4ce307 to 6a9a0efe66eb (10 revisions) (flutter/flutter#187609)
2026-06-05 engine-flutter-autoroll@skia.org Roll Skia from 494f1bf55f51 to 6e003d7f69c8 (2 revisions) (flutter/flutter#187607)
2026-06-05 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from ZE1Jy9CtVVi-tjBAE... to N_LiSaBSUsE2LDZgG... (flutter/flutter#187597)
2026-06-05 engine-flutter-autoroll@skia.org Roll Skia from 59556fdb8c33 to 494f1bf55f51 (2 revisions) (flutter/flutter#187596)
2026-06-04 engine-flutter-autoroll@skia.org Roll Skia from 8eb107046fd5 to 59556fdb8c33 (1 revision) (flutter/flutter#187590)
2026-06-04 34871572+gmackall@users.noreply.github.com Remove `embedded_android_views_integration_test.dart` (flutter/flutter#187465)
2026-06-04 burak.karahan@mail.ru Remove Material imports from rendering editable tests (flutter/flutter#186951)
2026-06-04 jason-simmons@users.noreply.github.com [Impeller] Wait for the Vulkan device to become idle before destroying Vulkan objects in the AHBSwapchainImplVK destructor (flutter/flutter#187477)
2026-06-04 chris@bracken.jp [iOS] Eliminate unnecessary redeclaration of FlutterDisplayLink (flutter/flutter#187557)
2026-06-04 engine-flutter-autoroll@skia.org Roll Skia from 928ded2a31af to 8eb107046fd5 (1 revision) (flutter/flutter#187583)
2026-06-04 34871572+gmackall@users.noreply.github.com Log stdout in adb.dart (flutter/flutter#187531)
2026-06-04 mvincentong@gmail.com Clarify RouterDelegate popRoute bubbling (flutter/flutter#186875)
2026-06-04 engine-flutter-autoroll@skia.org Roll Skia from 928ded2a31af to 8eb107046fd5 (1 revision) (flutter/flutter#187584)
2026-06-04 1063596+reidbaker@users.noreply.github.com Add updating-android-sdk agent skill for rolling Android SDK in CIPD (flutter/flutter#187576)
2026-06-04 Rusino@users.noreply.github.com Fixing alignment issue (flutter/flutter#187518)
2026-06-04 brackenavaron@gmail.com [Material Cross Imports] Clean up Material Divider usages (flutter/flutter#187300)
2026-06-04 engine-flutter-autoroll@skia.org Roll Skia from cecc0e0da9ae to 928ded2a31af (6 revisions) (flutter/flutter#187574)
2026-06-04 31859944+LongCatIsLooong@users.noreply.github.com Use swift demangle to verify internal Swift symbols (flutter/flutter#186835)
2026-06-04 1063596+reidbaker@users.noreply.github.com Add android 37 platform and build tools to script for android cipd bundle creation (flutter/flutter#187571)
2026-06-04 jason-simmons@users.noreply.github.com [Impeller] Increase the precision of the IPSampleWithTileModeOES coords parameter to match the input coordinates in the tiled_texture_fill_external shader (flutter/flutter#187545)
2026-06-04 engine-flutter-autoroll@skia.org Roll Packages from b11504f to 03352b5 (4 revisions) (flutter/flutter#187569)
2026-06-04 iinozemtsev@google.com Roll Dart SDK to Dart 3.13 beta2 (flutter/flutter#187555)
2026-06-04 engine-flutter-autoroll@skia.org Roll Skia from 611e3f8ceb93 to cecc0e0da9ae (1 revision) (flutter/flutter#187562)
2026-06-04 6655696+guidezpl@users.noreply.github.com Add step to bootstrap Flutter tool in coverage workflow (flutter/flutter#187199)
2026-06-04 engine-flutter-autoroll@skia.org Roll Skia from 4fdb859c8da7 to 611e3f8ceb93 (4 revisions) (flutter/flutter#187554)
2026-06-04 engine-flutter-autoroll@skia.org Roll Skia from 0020aae33f63 to 4fdb859c8da7 (2 revisions) (flutter/flutter#187552)
2026-06-04 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from ap7MhLX4TdpWRrLS_... to ZE1Jy9CtVVi-tjBAE... (flutter/flutter#187550)
2026-06-04 stuartmorgan@google.com Add vector_math to package issue template (flutter/flutter#187536)
2026-06-04 jason-simmons@users.noreply.github.com Manual roll Dart SDK from d39850bf4a01 to 3b70b98fa7c0 (flutter/flutter#187519)
2026-06-04 engine-flutter-autoroll@skia.org Roll Skia from d625048c853a to 0020aae33f63 (20 revisions) (flutter/flutter#187539)
2026-06-04 smille2003@yandex.ru [Impeller][Windows] fix black screen on OpenGL fallback (flutter/flutter#187288)
2026-06-04 97480502+b-luk@users.noreply.github.com Fix unintentionally joined path contours (flutter/flutter#187522)
2026-06-03 matt.boetger@gmail.com fix: resolve issue #177379 by using lazy buildDirectory.dir() API in build.gradle template (flutter/flutter#187127)
2026-06-03 34871572+gmackall@users.noreply.github.com Add a skill for flake analysis (flutter/flutter#187530)
2026-06-03 30870216+gaaclarke@users.noreply.github.com adds linux impeller project flag (flutter/flutter#186982)
2026-06-03 codedoctor@linwood.dev Add support for stylus buttons (flutter/flutter#183369)
2026-06-03 46920873+gabrimatic@users.noreply.github.com Prevent Cubic transform from looping on out-of-range input (flutter/flutter#185875)
2026-06-03 bdero@google.com [Impeller] Reland: Allow attaching specific texture mip levels and slices (flutter/flutter#187470)
2026-06-03 kjlubick@users.noreply.github.com [skia] Update image deserial proc (flutter/flutter#185041)
2026-06-03 112751483+shivanshu877@users.noreply.github.com docs: update Impeller advanced blend docs for framebuffer fetch (flutter/flutter#185457)
2026-06-03 ahmedsameha1@gmail.com Handle#6537 fifth grouped tests (flutter/flutter#183720)

If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
...
creatorpiyush pushed a commit to creatorpiyush/packages that referenced this pull request Jun 10, 2026
@engine-flutter-autoroll
Roll Flutter from 2ba5420a7049 to 1bdf4af29076 (43 revisions) (flutte…
8b227e8 
…r#11849)

Roll Flutter from 2ba5420a7049 to 1bdf4af29076 (43 revisions)

flutter/flutter@2ba5420...1bdf4af

2026-06-05 engine-flutter-autoroll@skia.org Roll Packages from 03352b5 to 61bdbb4 (5 revisions) (flutter/flutter#187612)
2026-06-05 engine-flutter-autoroll@skia.org Roll Skia from 6e003d7f69c8 to a47a9a2c8ae5 (1 revision) (flutter/flutter#187610)
2026-06-05 engine-flutter-autoroll@skia.org Roll Dart SDK from aad8be4ce307 to 6a9a0efe66eb (10 revisions) (flutter/flutter#187609)
2026-06-05 engine-flutter-autoroll@skia.org Roll Skia from 494f1bf55f51 to 6e003d7f69c8 (2 revisions) (flutter/flutter#187607)
2026-06-05 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from ZE1Jy9CtVVi-tjBAE... to N_LiSaBSUsE2LDZgG... (flutter/flutter#187597)
2026-06-05 engine-flutter-autoroll@skia.org Roll Skia from 59556fdb8c33 to 494f1bf55f51 (2 revisions) (flutter/flutter#187596)
2026-06-04 engine-flutter-autoroll@skia.org Roll Skia from 8eb107046fd5 to 59556fdb8c33 (1 revision) (flutter/flutter#187590)
2026-06-04 34871572+gmackall@users.noreply.github.com Remove `embedded_android_views_integration_test.dart` (flutter/flutter#187465)
2026-06-04 burak.karahan@mail.ru Remove Material imports from rendering editable tests (flutter/flutter#186951)
2026-06-04 jason-simmons@users.noreply.github.com [Impeller] Wait for the Vulkan device to become idle before destroying Vulkan objects in the AHBSwapchainImplVK destructor (flutter/flutter#187477)
2026-06-04 chris@bracken.jp [iOS] Eliminate unnecessary redeclaration of FlutterDisplayLink (flutter/flutter#187557)
2026-06-04 engine-flutter-autoroll@skia.org Roll Skia from 928ded2a31af to 8eb107046fd5 (1 revision) (flutter/flutter#187583)
2026-06-04 34871572+gmackall@users.noreply.github.com Log stdout in adb.dart (flutter/flutter#187531)
2026-06-04 mvincentong@gmail.com Clarify RouterDelegate popRoute bubbling (flutter/flutter#186875)
2026-06-04 engine-flutter-autoroll@skia.org Roll Skia from 928ded2a31af to 8eb107046fd5 (1 revision) (flutter/flutter#187584)
2026-06-04 1063596+reidbaker@users.noreply.github.com Add updating-android-sdk agent skill for rolling Android SDK in CIPD (flutter/flutter#187576)
2026-06-04 Rusino@users.noreply.github.com Fixing alignment issue (flutter/flutter#187518)
2026-06-04 brackenavaron@gmail.com [Material Cross Imports] Clean up Material Divider usages (flutter/flutter#187300)
2026-06-04 engine-flutter-autoroll@skia.org Roll Skia from cecc0e0da9ae to 928ded2a31af (6 revisions) (flutter/flutter#187574)
2026-06-04 31859944+LongCatIsLooong@users.noreply.github.com Use swift demangle to verify internal Swift symbols (flutter/flutter#186835)
2026-06-04 1063596+reidbaker@users.noreply.github.com Add android 37 platform and build tools to script for android cipd bundle creation (flutter/flutter#187571)
2026-06-04 jason-simmons@users.noreply.github.com [Impeller] Increase the precision of the IPSampleWithTileModeOES coords parameter to match the input coordinates in the tiled_texture_fill_external shader (flutter/flutter#187545)
2026-06-04 engine-flutter-autoroll@skia.org Roll Packages from b11504f to 03352b5 (4 revisions) (flutter/flutter#187569)
2026-06-04 iinozemtsev@google.com Roll Dart SDK to Dart 3.13 beta2 (flutter/flutter#187555)
2026-06-04 engine-flutter-autoroll@skia.org Roll Skia from 611e3f8ceb93 to cecc0e0da9ae (1 revision) (flutter/flutter#187562)
2026-06-04 6655696+guidezpl@users.noreply.github.com Add step to bootstrap Flutter tool in coverage workflow (flutter/flutter#187199)
2026-06-04 engine-flutter-autoroll@skia.org Roll Skia from 4fdb859c8da7 to 611e3f8ceb93 (4 revisions) (flutter/flutter#187554)
2026-06-04 engine-flutter-autoroll@skia.org Roll Skia from 0020aae33f63 to 4fdb859c8da7 (2 revisions) (flutter/flutter#187552)
2026-06-04 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from ap7MhLX4TdpWRrLS_... to ZE1Jy9CtVVi-tjBAE... (flutter/flutter#187550)
2026-06-04 stuartmorgan@google.com Add vector_math to package issue template (flutter/flutter#187536)
2026-06-04 jason-simmons@users.noreply.github.com Manual roll Dart SDK from d39850bf4a01 to 3b70b98fa7c0 (flutter/flutter#187519)
2026-06-04 engine-flutter-autoroll@skia.org Roll Skia from d625048c853a to 0020aae33f63 (20 revisions) (flutter/flutter#187539)
2026-06-04 smille2003@yandex.ru [Impeller][Windows] fix black screen on OpenGL fallback (flutter/flutter#187288)
2026-06-04 97480502+b-luk@users.noreply.github.com Fix unintentionally joined path contours (flutter/flutter#187522)
2026-06-03 matt.boetger@gmail.com fix: resolve issue #177379 by using lazy buildDirectory.dir() API in build.gradle template (flutter/flutter#187127)
2026-06-03 34871572+gmackall@users.noreply.github.com Add a skill for flake analysis (flutter/flutter#187530)
2026-06-03 30870216+gaaclarke@users.noreply.github.com adds linux impeller project flag (flutter/flutter#186982)
2026-06-03 codedoctor@linwood.dev Add support for stylus buttons (flutter/flutter#183369)
2026-06-03 46920873+gabrimatic@users.noreply.github.com Prevent Cubic transform from looping on out-of-range input (flutter/flutter#185875)
2026-06-03 bdero@google.com [Impeller] Reland: Allow attaching specific texture mip levels and slices (flutter/flutter#187470)
2026-06-03 kjlubick@users.noreply.github.com [skia] Update image deserial proc (flutter/flutter#185041)
2026-06-03 112751483+shivanshu877@users.noreply.github.com docs: update Impeller advanced blend docs for framebuffer fetch (flutter/flutter#185457)
2026-06-03 ahmedsameha1@gmail.com Handle#6537 fifth grouped tests (flutter/flutter#183720)

If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
...
via-guy pushed a commit to via-guy/flutter that referenced this pull request Jun 26, 2026
@mvincentong @AbdeMohlbi @via-guy
Clarify RouterDelegate popRoute bubbling (flutter#186875)
ed50ec8 
Fixes flutter#118975.

`RouterDelegate.popRoute` said returning false would cause the entire
app to be popped, which skips an important nested-router detail. In a
nested `Router` setup, returning false means this delegate did not
handle the pop request, so the request can continue through a parent
`BackButtonDispatcher`; only an unhandled request that reaches the root
binding triggers the application pop behavior.

Verification:
- `./bin/dart format packages/flutter/lib/src/widgets/router.dart`
- `./bin/flutter analyze packages/flutter/lib/src/widgets/router.dart`
- `git diff --check`

Co-authored-by: Mohellebi Abdessalem <116356835+AbdeMohlbi@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@justinmc justinmc justinmc approved these changes
@AbdeMohlbi AbdeMohlbi AbdeMohlbi approved these changes
+1 more reviewer
@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

CICD Run CI/CD f: routes Navigator, Router, and related APIs. framework flutter/packages/flutter repository. See also f: labels.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

popRoute() documentation is misleading

3 participants

@mvincentong @justinmc @AbdeMohlbi