
# Transitions

By default a screen comes in as the app type's own routes do, as in Flutter: Material's transition for the platform in a `MaterialApp`, the iOS slide in a `CupertinoApp`, none in an app without a design library. The theme sets another for every screen with `spring.flutter.theme.motion.page-transition` (`none` switches pages at once); a screen, or a single navigation, can choose its own.

## Why

A transition is part of the look of an app, so it belongs to the theme: a designer changes it in YAML, per platform if needed (a platform is a profile), and the router follows in a `MaterialApp`, a `CupertinoApp` and a `WidgetsApp` alike. A menu that switches pages should not animate at all; that is a choice per navigation.

## Example

```yaml
# Pages that switch at once, in every app type.
spring:
  flutter:
    theme:
      motion:
        page-transition: none
```

```yaml
# A fade of a given duration and curve.
spring:
  flutter:
    theme:
      motion:
        page-transition: { type: fade, duration: 200ms, curve: ease-out }
```

```dart
// One screen chooses its own.
@ScreenRoute('/settings', transition: PageTransition.none)
class SettingsPage extends StatelessWidget { ... }

// One navigation too: a menu that switches pages at once.
context.route.go('/motion', transition: PageTransition.none);
```

## The values

| `PageTransition` | Theme value | Meaning |
|---|---|---|
| `theme` | | The theme's `motion.page-transition`, `platform` when it sets nothing (the default of a screen) |
| `platform` | `platform` | The app type's own: Material's transition for the platform in a `MaterialApp`, the iOS slide in a `CupertinoApp`, none in an app without a design library (the theme's default) |
| `fadeUpwards` | `fade-upwards` | The fade upwards of Android, in any app type |
| `zoom` | `zoom` | Material's zoom, in any app type with `spring_boot_starter_flutter_material` in the dependencies |
| `cupertino` | `cupertino` | The iOS slide with its swipe back, in any app type with `spring_boot_starter_flutter_cupertino` in the dependencies |
| `fade` | `fade` | A fade |
| `content` | `content` | As the theme's `motion.content-change`: the way a part of a screen shows other content (`fade-up`), with its duration and curve |
| `none` | `none` | At once |

- The kinds take the theme's duration and curve when it sets them (`{ type, duration, curve }`, references such as `$motion.durations.fast` allowed).
- With reduced motion on the device every transition is instant.
- Switching the branches of a shell never animates.

## As in Flutter, and where it differs

In Flutter the route chooses the transition, and each `Navigator.push` chooses its route class:

| App | Flutter's transition |
|---|---|
| `MaterialApp` (`MaterialPageRoute`) | `ThemeData.pageTransitionsTheme`, one builder per platform: `PredictiveBackPageTransitionsBuilder` on Android, `CupertinoPageTransitionsBuilder` on iOS and macOS, `ZoomPageTransitionsBuilder` on Windows and Linux |
| `CupertinoApp` (`CupertinoPageRoute`) | The iOS slide, with the swipe back from the edge |
| `WidgetsApp` | None of its own: the app gives a `pageRouteBuilder` |

The default here is the same, `platform`, so an app that sets nothing looks as Flutter's would.

**One theme value instead of builders per platform.** The look is configuration: `motion.page-transition` is in `application.yml`, per theme (`themes.<name>`) and per profile, and a platform is a profile:

```yaml
# lib/resources/application-web.yml: the web pages switch at once
spring.flutter.theme.motion.page-transition: none
```

The same value drives the router's screens and Material's own routes (a `MaterialPageRoute` pushed by code takes it through `pageTransitionsTheme`). Builders per platform in code still work: a `ThemeCustomizer` that sets `pageTransitionsTheme` ([Themes in code](../spring-boot-starter-flutter-material/themes-in-code.md)), and a page that asks for `platform` then uses them.

**What Flutter has no counterpart for:**

- A screen chooses its own (`@ScreenRoute(transition: PageTransition.fade)`), and one navigation too (`go(path, transition: PageTransition.none)`), with no route class of its own.
- Duration and curve come from the theme for every kind, `platform` included (`{ type: platform, duration: 250ms, curve: ease-out }`).
- `content`: a screen comes in as `motion.content-change` shows other content.
- Reduced motion on the device makes every transition instant.
- Switching the branches of a shell never animates.
- `zoom` and `cupertino` work in any app type with their starter: the iOS slide in a `MaterialApp`, Material's zoom in a `WidgetsApp`.

**Why it used to be none, and when to write `none`.** Until 0.8 a theme without `motion.page-transition` had no transition, in every app type. An app without a design library (a web site such as farum-azula.org) switches pages at once anyway, and content sites and dashboards often want instant pages; a Material or Cupertino app, though, had less than Flutter gives it. For pages that switch at once, write `motion.page-transition: none`.

## Transitions of a design library

The router imports neither Material nor Cupertino. The routes of `platform` in a `MaterialApp` or a `CupertinoApp`, and of `cupertino`, come from the `DesignPageRoutes` beans of the design starters (`MaterialPageRoutes` of [spring_boot_starter_flutter_material](../spring-boot-starter-flutter-material/other-starters.md), `CupertinoPageRoutes` of [spring_boot_starter_flutter_cupertino](../spring-boot-starter-flutter-cupertino/other-starters.md)), asked in `@Order`. An app of type `material` or `cupertino` has them with its starter. `fade`, `fade-upwards`, `content` and `none` are the Flutter starter's own and work in any app.

`zoom` and `cupertino` need their starter:

- In the theme (`motion.page-transition`), the start fails and names the starter to add.
- On a screen (`@ScreenRoute(transition: ...)`) or in one navigation (`go(..., transition: ...)`), the error is reported, naming the starter, and the page shows without a transition.

## See also

- [Motion and animations](../spring-boot-starter-flutter/themes/motion-and-animations.md)
- [Design libraries](../spring-boot-starter-flutter/design-libraries.md)
- [Screens and routes](screens.md)
- [Shells and tabs](shells.md)
