
# Page transitions

On iOS a new screen slides in from the right, the screen below moves a little to the left in a shadow, and a swipe from the left edge takes the screen back, following the finger. This starter gives that transition to the router of [spring_boot_starter_flutter_navigation](../spring-boot-starter-flutter-navigation/index.md), from the theme: `motion.page-transition: cupertino` in an app of any type, or `platform` in an app of type `cupertino`.

## Why

- **The transition belongs to the theme.** A designer changes it in YAML, per theme or per platform, like a color; no route class is written in Dart.
- **A `CupertinoApp` slides by default, as in Flutter.** A theme without `motion.page-transition` is `platform`, the app type's own: the iOS slide in a `CupertinoApp`, as Flutter's `CupertinoPageRoute` has it. Pages that should switch at once say `none` (see [Transitions](../spring-boot-starter-flutter-navigation/transitions.md#as-in-flutter-and-where-it-differs)).
- **The swipe back comes with it.** Users of iPhones go back with a swipe from the edge; the iOS route has the gesture, a plain fade does not.

## Example

```yaml
# lib/resources/application.yml: the app type's own transition (the default, written out), the iOS slide in a CupertinoApp
spring:
  flutter:
    theme:
      motion:
        page-transition: platform
```

```yaml
# the iOS slide in an app of any type, with its own duration and curve
spring:
  flutter:
    theme:
      motion:
        durations: { medium: 350ms }
        page-transition:
          type: cupertino
          duration: $motion.durations.medium
          curve: ease-out
```

```properties
# the same in lib/resources/application.properties
spring.flutter.theme.motion.page-transition.type=cupertino
spring.flutter.theme.motion.page-transition.duration=350ms
spring.flutter.theme.motion.page-transition.curve=ease-out
```

## The values

`motion.page-transition` is a kind alone, or a map of `type`, `duration` and `curve` (see [Motion and animations](../spring-boot-starter-flutter/themes/motion-and-animations.md#page-transitions)). In an app with this starter:

| Value | In an app of type `cupertino` | In an app of another type |
|---|---|---|
| none set, or `platform` | The iOS slide, with the swipe back | Material's transition in a `MaterialApp`; none in a `WidgetsApp` |
| `none` | No transition: the screen shows at once | The same |
| `cupertino` | The iOS slide, with the swipe back | The iOS slide, with the swipe back |
| `fade`, `fade-upwards`, `content` | The Flutter starter's own | The same |
| `zoom` | Material's: needs the [Material starter](../spring-boot-starter-flutter-material/other-starters.md) | The same |

| Key of the map | Type | Default | What it does |
|---|---|---|---|
| `type` | enum | `platform` | The kind, as above |
| `duration` | duration (`350ms`, `$motion.durations.medium`) | iOS's own: 500 ms | How long the slide takes, in both directions |
| `curve` | curve (`ease-out`, four numbers, `$motion.curves.<name>`) | none: the slide's own easing | Shapes the animation the slide follows |

With reduced motion on the device every transition is instant, the iOS slide too.

## The swipe back

The route of the slide is Cupertino's own (`CupertinoRouteTransitionMixin`), so it behaves as on iOS:

- A drag from the leading edge (the left; the right in a right-to-left language) takes the screen back, and the transition follows the finger linearly. Let go past the middle, or with a flick, and the screen goes back; otherwise it returns.
- The first screen of a navigator has no swipe back: there is nothing to go back to.
- A screen that refuses to be left (a `PopScope` with `canPop: false`, such as a form with unsaved changes) cannot be swiped away either.
- The gesture works on every platform, not only on iOS: with `cupertino`, an Android phone has it too.

## Over a theme background

While a page slides in, iOS dims the page below with a light black, and the route keeps that layer under its page. A theme with a [`background`](../spring-boot-starter-flutter/themes/background.md) shows it through every screen, so the layer would stay on it and make it darker than the theme says: with a background the route draws none. Without one the page covers the layer, as in Flutter.

## Heroes

In an app of type `cupertino`, the heroes of the router's navigators fly in a straight line, as `CupertinoApp` makes them fly (`CupertinoApp.createCupertinoHeroController()`). In an app of another type, the transition `cupertino` keeps that app's hero flights.

## Per screen and per navigation

The theme's transition is the default of every screen. A screen chooses its own, and one navigation too, with the navigation starter's `PageTransition`; `PageTransition.cupertino` is the iOS slide, `PageTransition.platform` the app type's own:

```dart
@ScreenRoute('/books/:id', transition: PageTransition.cupertino)
class BookPage extends StatelessWidget { ... }

// A menu that switches pages at once.
context.route.go('/settings', transition: PageTransition.none);
```

They take the theme's duration and curve. See [Transitions](../spring-boot-starter-flutter-navigation/transitions.md).

## Without the starter

`cupertino` is the Cupertino starter's: the Flutter starter and the navigation starter import no Cupertino.

- In the theme (`motion.page-transition: cupertino`), the start fails and names the starter to add:

  ```text
  Invalid theme property spring.flutter.theme.motion.pagetransition.type (theme light): 'cupertino'; expected a transition of the application: cupertino is Cupertino's, read by spring_boot_starter_flutter_cupertino (add it to the dependencies), or platform, fade-upwards, fade, content or none.
  ```

- On a screen or in one navigation (`PageTransition.cupertino`), the error is reported in the log, naming the starter, and the page shows without a transition. It is not thrown: the navigator is updating its pages at that moment.
- `platform` without a design starter shows no transition.

## Without the router

The theme's transitions are the router's. A screen pushed by hand with Flutter's `Navigator.push` and a `CupertinoPageRoute` keeps Cupertino's slide with its own duration, whatever the theme says.

## How it works

The router asks the `DesignPageRoutes` beans, in `@Order`, for the route of each page. This starter's bean, `cupertinoPageRoutes` (`CupertinoPageRoutes`), answers for `cupertino` in an app of any type and for `platform` in an app of type `cupertino`, with a route that has the theme's duration and curve; for every other transition it answers `null`, and the next bean or the router's own transitions take over. See [Page routes: DesignPageRoutes](../spring-boot-starter-flutter/design-libraries.md#page-routes-designpageroutes).

## See also

- [Transitions of the navigation starter](../spring-boot-starter-flutter-navigation/transitions.md)
- [Motion and animations](../spring-boot-starter-flutter/themes/motion-and-animations.md)
- [With the other starters](other-starters.md)
- [Design libraries](../spring-boot-starter-flutter/design-libraries.md)
