Shared element transition for predictive back

[maRci002]

This PR adds a shared element transition for predictive back navigation, based on the specification found here: https://developer.android.com/design/ui/mobile/guides/patterns/predictive-back#shared-element-transition.

A new transition builder added: PredictiveBackPageSharedElementTransitionsBuilder, which constructs the shared element transition version.

Code sample

import 'package:flutter/material.dart';

void main() {
  runApp(const MainApp());
}

class MainApp extends StatelessWidget {
  const MainApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        brightness: Brightness.light,
        pageTransitionsTheme: const PageTransitionsTheme(
          builders: {
            TargetPlatform.android: PredictiveBackPageSharedElementTransitionsBuilder(),
          },
        ),
      ),
      home: const FirstScreen(),
    );
  }
}

class FirstScreen extends StatelessWidget {
  const FirstScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('First Screen'),
      ),
      body: Center(
        child: ElevatedButton(
          onPressed: () {
            Navigator.of(context).push(
              MaterialPageRoute(builder: (_) => const SecondScreen()),
            );
          },
          child: const Text('Go to Second Screen'),
        ),
      ),
    );
  }
}

class SecondScreen extends StatelessWidget {
  const SecondScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Theme(
      data: ThemeData(brightness: Brightness.dark),
      child: Scaffold(
        appBar: AppBar(
          title: const Text('Second Screen'),
        ),
        body: const Center(
          child: Text('Hello, Predictive back!'),
        ),
      ),
    );
  }
}

predictive_back_shared_element.webm

Partial fix for #153577

[flutter-dashboard]

It looks like this pull request may not have tests. Please make sure to add tests before merging. If you need an exemption, contact "@test-exemption-reviewer" in the #hackers channel in Discord (don't just cc them here, they won't see it!).

If you are not sure if you need tests, consider this rule of thumb: the purpose of a test is to make sure someone doesn't accidentally revert the fix. Ask yourself, is there anything in your PR that you feel it is important we not accidentally revert back to how it was before your fix?

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing. The test exemption team is a small volunteer group, so all reviewers should feel empowered to ask for tests, without delegating that responsibility entirely to the test exemption group.

[maRci002]

cc @justinmc I have opened this PR as we discussed. I will add tests and documentation once the PR looks good.

[Piinks]

Hi @maRci002 thanks for contributing! It looks like there are some failing checks, can you take a look?

[justinmc]

Thanks for jumping on this! Sorry I missed the notification.

Two slight inconsistencies I notice when I try the native Settings app on the latest beta:

1. The previous route sits slightly offscreen to the left and also moves vertically when you drag vertically. I guess that's probably not easily doable. Possibly with @MitchellGoodwin's recent work in #150031.

2. After releasing the gesture, the outgoing route fades out on native, but on your branch I see it scale and then suddenly disappear.

Can you take a look and see if you can get closer to native on either of those 2 points? Otherwise this is a huge improvement and I'm on board with landing this approach.

XRecorder_Edited_27092024_153502.mp4

[justinmc]

I think PredictiveBackPageTransitionBuilder should probably do the shared element transition, since that seems to be the default on native Android? Then we would have a separate PredictiveBackFullScreenPageTransitionBuilder for that transition. Or we could even delete it... Do we know if the full screen transition exists on native Android? Like can I choose to use it when writing a native Android app? It's hard to tell since everything is in beta still.

[maRci002]

Oh yeah, the PredictiveBackPageTransitionBuilder should provide the new transition out of the box, and the old one could be renamed or removed.

[Piinks]

@maRci002 do you plan to continue working on this PR?

[maRci002]

Yes, I plan to continue working on this PR. I will soon make one of my phones operational to see the native behavior accurately. I will place this PR in draft until then.

[flutter-dashboard]

This pull request has been changed to a draft. The currently pending flutter-gold status will not be able to resolve until a new commit is pushed or the change is marked ready for review again.

For more guidance, visit Writing a golden file test for package:flutter.

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing.

[maRci002]

On Android 14, the Settings app uses the Full Screen Surfaces animation, while on Android 15, the Settings app uses the Shared Element transition. More about these concepts: GitHub Issue Comment.

Here is the predictive back animation on Android 15 (with both Transition animation scale and Animator duration scale set to 10x in the Developer options):

output.mp4

2. After releasing the gesture, the outgoing route fades out on native, but on your branch I see it scale and then suddenly disappear.

The only problem is that we are driving the route via _PredictiveBackGestureDetector. At this point, the page transition is nearly 100%, so I can't rely on the fade-out starting at 80%, because the user might change their mind and cancel the predictive back gesture. This means the _PredictiveBackGestureDetector should provide a phase to let the builder know whether it's in the commit phase. I think the actual transition should handle its own animation when the commit starts.

[justinmc]

@maRci002 Can you re-upload that video? It doesn't ever start playing for me.

[maRci002]

@maRci002 Can you re-upload that video? It doesn't ever start playing for me.

settings.app.predictive.back.mp4

Here is the default back button behavior; this will be implemented by #142352:

settings.app.back.button.mp4

1. The previous route sits slightly offscreen to the left and also moves vertically when you drag vertically. I guess that's probably not easily doable. Possibly with @MitchellGoodwin's recent work in Allow mixing route transitions in one app. #150031.

When route.popGestureInProgress == false, we fall back to ZoomPageTransitionsBuilder, which might be replaced by #142352. This means the previous route will animate offscreen by default. For reference, see the attached video about Android 15 back button behavior.
However, I can use #150031; the previous route should also be scaled/transitioned, which means I need actual predictive back events. The problem is that predictive back events from WidgetsBinding._backGestureObserver are sent only to the active observer.

Here is a pseudo code about prev route problem:

class PredictiveBackPageSharedElementTransitionsBuilder extends PageTransitionsBuilder {
  const PredictiveBackPageSharedElementTransitionsBuilder();

  @override
  Widget delegatedTransition(BuildContext context, Animation<double> animation, Animation<double> secondaryAnimation, bool allowSnapshotting, Widget? child) {
    // Problems:
    // We don't know the topmost Route.
    // We cannot listen to predictive back events since WidgetsBinding sends them only to the active listener, which is the _PredictiveBackGestureDetector inside the buildTransitions method
  }

  @override
  Widget buildTransitions<T>() {
    return _PredictiveBackGestureDetector<T>(
      route: route,
      builder: () {
        if (route.popGestureInProgress) {
          return _PredictiveBackPageSharedElementTransition();
        }

        return const ZoomPageTransitionsBuilder().buildTransitions();
      },
    );
  }
}

[maRci002]

2. After releasing the gesture, the outgoing route fades out on native, but on your branch I see it scale and then suddenly disappear.

I made some changes and set timeDilation to 2.0, but unfortunately, my emulator is a bit slow.

fade_out.mp4

[justinmc]

I'm able to see your videos on my Mac but not on my Linux machine. Strange but I guess that is doable 🤷 .

Thank you for all of your assessment. I'm on board with everything you said. So in the latest Android the default page transition is the Shared Axis transition (#142352, which is being worked on), and when doing predictive back it uses the Shared Element transition (which this PR implements).

So we are on track to match the latest version of native Android. PredictiveBackPageTransitionBuilder will be updated to use your _PredictiveBackPageSharedElementTransition and fall back to the upcoming Shared Axis transition.

Problems for the incoming route when swiping back

I think we could merge this PR without support for animating the incoming route. Your latest video you posted looks quite good without it. But let's talk through those problems.

We don't know the topmost route

Is that necessary? See for example @MitchellGoodwin's new PR that implements modal bottom sheet using delegatedTransition. Could you do something similar or am I misunderstanding?

https://github.com/flutter/flutter/pull/157568/files#diff-46d8c09c856d9697ebf30eb9e88b0eab83a0e3ca439711968544927bc9ec4daaR107

We can't listen to predictive back events

The problem is that predictive back events from WidgetsBinding._backGestureObserver are sent only to the active observer.

This pattern of notifying the first observer keeps coming back to haunt me. I should have tried harder to move away from it for predictive back.

What if we change it to notify all observers? I think that's the way that this pattern was meant to be used. However, we still need a return value, so it would have to be something like this:

  WidgetsBindingObserver? _backGestureObserver;

  Future<bool> _handleStartBackGesture(Map<String?, Object?> arguments) {
    _backGestureObserver = null;
    final PredictiveBackEvent backEvent = PredictiveBackEvent.fromMap(arguments);
    bool handled = false;
    for (final WidgetsBindingObserver observer in List<WidgetsBindingObserver>.of(_observers)) {
      if (observer.handleStartBackGesture(backEvent)) {
        _backGestureObserver = observer;
        handled = true;
      }
    }
    return Future<bool>.value(handled);
  }

[justinmc]

@maRci002 How did it go when using delegatedTransition? I tried the PR locally and it didn't seem to move the incoming route at all.

[justinmc]

@maRci002 Do you still have plans to return to this PR? I'd be happy to help you review it. I do want to get this animation updated, so if not, maybe I can take over this PR again.

[maRci002]

Apologies for not addressing this pull request recently; I've been quite swamped. I do plan to continue working on it, especially now that the M3 page transition has been implemented. However, if time is of the essence, please feel free to take over and continue this PR.

[justinmc]

@maRci002 Thanks for following up. I'm winding down for the holidays here, so I will check on this PR again after the new year.

[Piinks]

Update: Caught up with Justin last week regarding this change, he plans to pick this up to finish.

[TheLastFlame]

I've been working on implementing this here: https://github.com/TheLastFlame/flutter/tree/shared-elements-predictive-back

It allows you to work with Hero, dialogs, and bottomsheets. However, there are still a few unresolved issues in the page transition implementation.

I'd be happy to join the discussion.

[TheLastFlame]

I was starting to make a demo for demoing and testing at the time, but temporarily abandoned it:

screen-20250322-172103.mp4

[auto-submit]

autosubmit label was removed for flutter/flutter/154718, because This PR has not met approval requirements for merging. The PR author is not a member of flutter-hackers and needs 1 more review(s) in order to merge this PR.

• Merge guidelines: A PR needs at least one approved review if the author is already part of flutter-hackers or two member reviews if the author is not a flutter-hacker before re-applying the autosubmit label. Reviewers: If you left a comment approving, please use the "approve" review action instead.

[justinmc]

LGTM 👍

I wrote most of this PR but the bot requires 2 approvals 😄 .

[maRci002]

Thank you so much, @justinmc, for your work the PR looks good to me.
I did notice a small bug: when you open the page and the animation is still ongoing, if you immediately perform the back gesture, it's not recognized. However, this can be fixed later.

screen-20250520-092537.mp4

@maRci002 do you remember why you animated both the size of the page and the padding?

The spec says:

Leave an 8 dp gap from the screen edge
Limit y-shift so the surface never passes the 8 dp screen margin

but I think the animation looks good now.