RouteAware.didPushNext documentation is incorrect #24594

Activity

1. alanrussian

   added

   customer: mulligan (g3)

   on Nov 21, 2018
2. zoechi

   added

   frameworkflutter/packages/flutter repository. See also f: labels.flutter/packages/flutter repository. See also f: labels.

   f: routesNavigator, Router, and related APIs.Navigator, Router, and related APIs.

   on Nov 21, 2018
3. zoechi

   added this to the GoalsThis milestone has been deleted milestone on Nov 21, 2018
4. dnfield

   added

   d: api docsIssues with https://api.flutter.dev/Issues with https://api.flutter.dev/

   on Nov 21, 2018
5. kf6gpe

   added

   P2Important issues not at the top of the work listImportant issues not at the top of the work list

   on May 29, 2020
6. Hixie

   removed this from the None.This milestone has been deleted milestone on Aug 17, 2020
7. darshankawar

   added

   documentation

   passed first triage

   on Sep 8, 2020
8. Hixie

   removed

   documentation

   on Jul 5, 2023
9. flutter-triage-bot

   added

   team-frameworkOwned by Framework teamOwned by Framework team

   triaged-frameworkTriaged by Framework teamTriaged by Framework team

   on Jul 8, 2023
10. Hixie

    removed

    passed first triage

    on Jul 8, 2023
11. ishaquehassan commented on Mar 1, 2026

    

    ishaquehassan

    on Mar 1, 2026

    Contributor

    More actions

    After tracing through the source code in routes.dart, I can confirm the documentation is indeed inaccurate.

    In RouteObserver.didPush() (around line 2506), routeAware.didPushNext() is called synchronously during the push operation, before the route transition animation completes. At this point, the current route is still partially visible (being animated away), not "no longer visible" as the documentation states.

    The current documentation:

    /// Called when a new route has been pushed, and the current route is no
    /// longer visible.
    void didPushNext() {}

    Suggested fix:

    /// 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.
    void didPushNext() {}

    This clarifies the exact timing and provides guidance for developers who need to act after the route is fully hidden.
12. ishaquehassan

    added a commit that references this issue on Mar 1, 2026

    Fix RouteAware.didPushNext documentation inaccuracy

    ...

    This issue will close once commit 7c1e2e0 is merged into the 'master' branch.

    7c1e2e0
13. github-merge-queue

    added a commit that references this issue on Mar 14, 2026

    Fix RouteAware.didPushNext documentation inaccuracy (#183097)

    ...

    24c18e6
14. auto-submit

    closed this as completedin #183097on Mar 14, 2026
15. mboetger

    added a commit that references this issue on Mar 26, 2026

    Fix RouteAware.didPushNext documentation inaccuracy (flutter#183097)

    ...

    4a81d46
16. github-actions commented on Mar 28, 2026

    

    github-actionsBot

    on Mar 28, 2026 – with GitHub Actions

    More actions

    This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of flutter doctor -v and a minimal reproduction of the issue.
17. github-actions

    locked as resolved and limited conversation to collaborators on Mar 28, 2026
18. ahmedsameha1

    added a commit that references this issue on Apr 14, 2026

    Fix RouteAware.didPushNext documentation inaccuracy (flutter#183097)

    ...

    81ecd44