Skip to content
Boring Doc
BreakingHigh impactOfficial migration guidesince 3.38.0landed 3.37.0-0.0.preandroid

The default page transition on Android is now PredictiveBackPageTransitionBuilder

Framework · Official source

What changed?

The default page transition on Android has been updated from `ZoomPageTransitionsBuilder` to `PredictiveBackPageTransitionsBuilder`. When not using predictive back, this falls back to `FadeForwardsPageTransitionsBuilder`.

Original behavior

Android has been rolling out a feature called predictive back, where performing a back gesture allows the user to peek at the previous route or app and possibly cancel the navigation. Flutter added support for this with the `PopScope` widget followed by `PredictiveBackPageTransitionsBuilder`.

New behavior

With this change, `PredictiveBackPageTransitionsBuilder` has replaced `ZoomPageTransitionsBuilder` as the default page transition on Android. During a normal page transition without a predictive back gesture, users see the new `FadeForwardsPageTransitionsBuilder` as the default page transition. When using a predictive back gesture, the page animates along with the gesture and allows canceling or committing to the back navigation.

Will this affect my application?

Who is affected
Applications and packages relying on the previous behaviour or signature. Code that uses ZoomPageTransitionsBuilder, PredictiveBackPageTransitionsBuilder, FadeForwardsPageTransitionsBuilder and related APIs.
Practical impact
Behaviour or API differences that can break builds or change runtime behaviour.
What action should I take?
Follow the official migration guide below, update affected call sites, run `dart fix --apply` where a fix is available, then run your tests.
APIs mentioned:ZoomPageTransitionsBuilderPredictiveBackPageTransitionsBuilderFadeForwardsPageTransitionsBuilderPopScopeTransitionDurationObserver

How do I migrate safely?

Before and after (from the official guide)

dart+7−3
Before
1−return MaterialApp(
2 theme: ThemeData(
3− brightness: Brightness.light,
4− // pageTransitionsTheme is the default.
 
 
 
 
5 ),
6 home: const MyFirstScreen(),
7 );
After
1+MaterialApp(
2 theme: ThemeData(
3+ // pageTransitionsTheme is explicitly set to the old transition on Android.
4+ pageTransitionsTheme: const PageTransitionsTheme(
5+ builders: {
6+ TargetPlatform.android: ZoomPageTransitionsBuilder(),
7+ },
8+ ),
9 ),
10 home: const MyFirstScreen(),
11 );
Raw before / after
return MaterialApp(
  theme: ThemeData(
    brightness: Brightness.light,
    // pageTransitionsTheme is the default.
  ),
  home: const MyFirstScreen(),
);
MaterialApp(
  theme: ThemeData(
    // pageTransitionsTheme is explicitly set to the old transition on Android.
    pageTransitionsTheme: const PageTransitionsTheme(
      builders: {
        TargetPlatform.android: ZoomPageTransitionsBuilder(),
      },
    ),
  ),
  home: const MyFirstScreen(),
);
Official migration guide (excerpt, © The Flutter Authors, CC BY 3.0)

If you want to keep your app's page transition on the old [ZoomPageTransitionsBuilder][], you can simply set your page transition explicitly in your app's theme. Keep in mind that you will not be able to support predictive back route transitions.

Code before migration:

return MaterialApp(
  theme: ThemeData(
    brightness: Brightness.light,
    // pageTransitionsTheme is the default.
  ),
  home: const MyFirstScreen(),
);

Code after migration:

MaterialApp(
  theme: ThemeData(
    // pageTransitionsTheme is explicitly set to the old transition on Android.
    pageTransitionsTheme: const PageTransitionsTheme(
      builders: {
        TargetPlatform.android: ZoomPageTransitionsBuilder(),
      },
    ),
  ),
  home: const MyFirstScreen(),
);

One side effect of changing the default transition is that the duration that it takes to transition between pages has increased from 300ms to 450ms. This might cause breakages in tests that depend on the previous transition duration. Fortunately, it's possible to use [TransitionDurationObserver][] to keep tests independent of whatever page transition is used.

Code before migration:

testWidgets('example', (WidgetTester tester) async {
  await tester.pumpWidget(
    MaterialApp(
      onGenerateRoute: (RouteSettings settings) { ... },
    ),
  );

  expect(find.text('Page 1'), findsOneWidget);
  expect(find.text('Page 2'), findsNothing);

  // Pump through the whole transition, hardcoded to 300ms.
  await tester.tap(find.text('Next'));
  await tester.pump(const Duration(milliseconds: 300));

  expect(find.text('Page 1'), findsNothing);
  expect(find.text('Page 2'), findsOneWidget);
});

Code after migration:

testWidgets('example', (WidgetTester tester) async {
  final TransitionDurationObserver observer = TransitionDurationObserver();

  await tester.pumpWidget(
    MaterialApp(
      navigatorObservers: <NavigatorObserver>[observer],
      onGenerateRoute: (RouteSettings settings) { ... },
    ),
  );

  expect(find.text('Page 1'), findsOneWidget);
  expect(find.text('Page 2'), findsNothing);

  // Pump through the whole transition independent of the duration.
  await tester.tap(find.text('Next'));
  await observer.pumpPastTransition(tester);

  expect(find.text('Page 1'), findsNothing);
  expect(find.text('Page 2'), findsOneWidget);
});

It's even possible to write tests that need to pump part of the way through a page transition without depending on the exact duration.

Code before migration:

testWidgets('example', (WidgetTester tester) async {
  await tester.pumpWidget(
    MaterialApp(
      onGenerateRoute: (RouteSettings settings) { ... },
    ),
  );

  expect(find.text('Page 1'), findsOneWidget);
  expect(find.text('Page 2'), findsNothing);

  // Pump through half of the transition with a hardcoded value.
  await tester.tap(find.text('Back'));
  await tester.pump(const Duration(milliseconds: 150));

  expect(find.text('Page 1'), findsOneWidget);
  expect(find.text('Page 2'), findsOneWidget);
});

Code after migration:

testWidgets('example', (WidgetTester tester) async {
  final TransitionDurationObserver observer = TransitionDurationObserver();

  await tester.pumpWidget(
    MaterialApp(
      navigatorObservers: <NavigatorObserver>[observer],
      onGenerateRoute: (RouteSettings settings) { ... },
    ),
  );

  expect(find.text('Page 1'), findsOneWidget);
  expect(find.text('Page 2'), findsNothing);

  // Pump through half of the transition independent of the duration.
  await tester.tap(find.text('Back'));
  await tester.pump(observer.transitionDuration ~/ 2);

  expect(find.text('Page 1'), findsOneWidget);
  expect(find.text('Page 2'), findsOneWidget);
});
Migration assistantAI-generated · grounded in cited sources
AI explanations are not configured
Set AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.

Evidence & verification

Official migration guide·Verified classification (95%)

Listed in the official breaking-changes index (docs.flutter.dev/release/breaking-changes).

An official announcement or migration guide documents an intended behaviour or API change. A verified source change (git diff) shows code changed but does not by itself prove a public API is breaking. AI interpretations are labelled and never used to classify a change.

Source commit
b3045439b7c0
Source last updated
Oct 21, 2026
Last synchronized
Oct 21, 2026
Publication status
published
Publication history
  • Oct 21, 2026, 8:31 PM: new → published (ingestion) — Backed by an official breaking-change/migration guide.
AI explanationAI-generated · grounded in cited sources
AI explanations are not configured
Set AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.
Was this useful?