Visitar URL original
Fix RouteAware.didPushNext documentation inaccuracy by ishaquehassan · Pull Request #183097 · flutter/flutter · GitHub
Skip to content
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Fix RouteAware.didPushNext documentation inaccuracy
The documentation incorrectly states that didPushNext is called when "the
current route is no longer visible". In reality, didPushNext is called
synchronously during the push operation, before the transition animation
completes. At this point, the current route may still be partially visible
as it animates out.

This commit corrects the documentation to accurately describe the timing
and provides guidance on how to detect when a route is fully obscured.

Fixes #24594
  • Loading branch information
ishaquehassan committed Mar 1, 2026
commit 7c1e2e0e2552dc00e59b3dc992f604185bb00fe0
9 changes: 7 additions & 2 deletions packages/flutter/lib/src/widgets/routes.dart
Original file line number Diff line number Diff line change
Expand Up @@ -2525,8 +2525,13 @@ abstract mixin class RouteAware {
/// Called when the current route has been popped off.
void didPop() {}

/// Called when a new route has been pushed, and the current route is no
/// longer visible.
/// Called when a new route has been pushed.

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.

This will mean didPush and didPushNext have the same API docs preview in RouteAware's documentation, can we somehow differentiate them in the opening line?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Good catch! Updated the opening line to "Called when a new route has been pushed on top of this route, temporarily obscuring it." which better captures the semantics and distinguishes it from didPush.

///
/// Note that this is called during the push operation, before the transition
/// animation completes. At this point the current route may still be
/// partially visible as it animates out. To perform actions after the route
/// is fully obscured, consider using [ModalRoute.animation] to listen for
/// animation completion.

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.

medium

This documentation update is a great improvement in accuracy. To make it even more helpful for developers, consider adding a small code snippet showing how to use ModalRoute.animation as you've suggested. This aligns with the Flutter style guide's recommendation to provide sample code where helpful.

  /// Called when a new route has been pushed.
  ///
  /// Note that this is called during the push operation, before the transition
  /// animation completes. At this point the current route may still be
  /// partially visible as it animates out. To perform actions after the route
  /// is fully obscured, consider using [ModalRoute.animation] to listen for
  /// animation completion, for example:
  ///
  /// ```dart
  /// ModalRoute.of(context)?.animation?.addStatusListener((AnimationStatus status) {
  ///   if (status == AnimationStatus.completed) {
  ///     // The new route is now fully visible and the old route is fully obscured.
  ///   }
  /// });
  /// ```
References
  1. The style guide recommends providing sample code to make documentation more useful. Adding a snippet for ModalRoute.animation would be a good example of this. (link)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Thanks for the suggestion! I've added a code snippet demonstrating how to use ModalRoute.animation with a status listener, as recommended. This should make it clearer for developers how to perform actions after the transition animation fully completes.

void didPushNext() {}
}

Expand Down