Motion and animations

Motion in a theme has two parts. motion holds durations and curves that you name, plus the page transition. animations holds named animations that play by themselves: how long, along which curve, and whether they repeat.

spring:
  flutter:
    theme:
      motion:
        page-transition: fade-upwards
        durations:
          fast: 120ms
          medium: 250ms
        curves:
          out: ease-out
          emphasized: [0.2, 0, 0, 1]
      animations:
        border-spin:
          duration: 4s
          curve: linear
          repeat: loop
        glow-pulse:
          duration: 1.6s
          curve: ease-in-out
          repeat: reverse

Properties

Property Type Values Default What it does
motion.enabled bool true, false true false makes every motion of the app instant, as the device's "reduce motion" does: page transitions, text and content changes, the scroll to the top, the theme's animations and Flutter's own. The debug panel's Motion tab switches it at run time
motion.page-transition enum, or a map platform, fade-upwards, zoom, cupertino, fade, content, none platform The page transition of every screen: the app type's own by default, as in Flutter; none switches pages at once. zoom needs spring_boot_starter_flutter_material, cupertino needs spring_boot_starter_flutter_cupertino
motion.page-transition.type / .duration / .curve enum / duration / curve as above, 200ms, a curve name the kind's own The map form: the kind with its duration and curve
motion.text-change enum, or a map none, fade, morph none What a ThemeText does when its text changes, another language say
motion.text-change.type / .duration / .curve / .stagger / .keep-unchanged / .glyphs / .glyph-duration enum / duration / curve / duration / boolean / text / duration as above, 450ms, a curve name, 12ms, true / false, any characters, a duration over zero none, 450ms, ease-out, 12ms, false, ▓▒░<>/|=+*#%&@$?!01, 40ms The map form; stagger is how much later each character of morph starts; keep-unchanged leaves the characters that stay the same in place
motion.overscroll platform, none platform What a scrollable shows when pulled past its end: the app type's own (Material's stretch on Android, which distorts the content for a moment) or nothing
motion.wheel-scroll none, or a map of duration, speed and inertia none (250ms, 1, no inertia in the map) How a mouse wheel scrolls every scrollable: none jumps by the wheel's step as Flutter does; a map eases each step over duration, scales it by speed, and gives each kind of pointer its inertia (inertia)
motion.scroll-to-top none, or a map of duration and curve 400ms, ease-out-cubic How a screen goes back to its top when it shows another page (RouteContentView); none jumps
motion.content-change a kind, or a map none, fade, fade-up, morph, or a kind of the app's own none How a part of a screen shows other content in its place (another page in RouteContentView)
motion.content-change.type / .duration / .curve kind / duration / curve as above, 200ms, a curve name none, 200ms, ease-out The map form
motion.content-change.stagger / .delay duration / duration 40ms, 650ms 30ms, none For morph: how much later each line starts than the one before it, and how long the new page waits before its first line
motion.durations.<name> duration 120ms, 1.5s, 2m, 1h short 100ms, medium 250ms, long 450ms A named duration
motion.curves.<name> curve a curve name, or four numbers standard A named curve
animations.<name>.duration duration 4s, 250ms required How long one run takes
animations.<name>.curve curve a curve name, or four numbers linear The curve of one run
animations.<name>.repeat enum none, loop, reverse none What happens at the end of a run

Inside motion only enabled, page-transition, text-change, content-change, scroll-to-top, wheel-scroll, overscroll, durations and curves exist. Inside an animation only duration, curve and repeat exist; another key stops the start and names the closest one.

Page transitions

motion.page-transition sets how screens come in and go out, for the whole app. The router of spring_boot_starter_flutter_navigation follows it in every app type (Material, Cupertino and widgets), and Material's own page routes follow it too.

zoom and cupertino come from a design library: zoom needs spring_boot_starter_flutter_material, cupertino needs spring_boot_starter_flutter_cupertino. With its starter in the dependencies, each works in an app of any type; in a theme without it, the start fails and names the starter. platform depends on the app's design. fade-upwards, fade, content and none are the Flutter starter's own and work in every app.

Value What it does
none No transition: the new page appears at once
platform The app type's own: Material's per platform in a MaterialApp (MaterialPageRoutes), the iOS slide in a CupertinoApp (CupertinoPageRoutes), none in an app without a design library (the default)
fade-upwards The new page slides up a little and fades in
zoom The new page grows from the centre while it fades in (Android 10 style). Material's: needs spring_boot_starter_flutter_material
cupertino The iOS slide from the right, with the swipe-back gesture, in any app type. Needs spring_boot_starter_flutter_cupertino
fade The new page fades in
content The new page comes in as motion.content-change shows other content (fade-up, a kind of the app's own), with its duration and curve unless the map form sets its own: the screens of a site change as its pages do

By default a screen comes in as the app type's own routes do, as in Flutter (platform). For pages that switch at once, in every app type:

spring:
  flutter:
    theme:
      motion:
        page-transition: none

Or choose and tune one: the map form gives the kind its duration and curve, which may refer to the theme's own ($motion.durations.fast):

spring:
  flutter:
    theme:
      motion:
        durations: { fast: 150ms }
        page-transition: { type: fade, duration: $motion.durations.fast, curve: ease-out }
      themes:
        cinema:
          motion:
            page-transition: zoom      # needs spring_boot_starter_flutter_material

A theme of themes.<name> may choose its own; switching themes applies to the next navigation. With reduced motion on the device every transition is instant. One screen can still choose its own (@ScreenRoute(transition: PageTransition.none)), and one navigation too (context.route.go(path, transition: PageTransition.none)): see the navigation starter. A screen's own zoom or cupertino without its starter is logged, naming the starter, and the page shows without a transition.

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:

# 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), and a page that asks for platform then uses them.

What Flutter has no counterpart for:

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.

Text changes

When the app's language switches, every text changes at once. Write motion.text-change and the texts shown with ThemeText change the theme's way instead:

spring:
  flutter:
    theme:
      motion:
        text-change: { type: morph, duration: 600ms, curve: ease-out, stagger: 12ms }
ThemeText(context.messages.home.title, style: theme.typography.displaySmall);
text-change:
  type: morph
  duration: 650ms
  stagger: 14ms
  glyphs: '01<>/'          # default ▓▒░<>/\|=+*#%&@$?!01
  glyph-duration: 30ms     # default 40ms

A ThemeText changes whenever the same widget gets another text: a new language, a value that updated, a result of a search as the query is typed. Its highlights (ranges of the text, the words a search found) show in highlightStyle once the change has settled. With reduced motion it changes at once. To act on the language itself, listen to the navigation's LanguageChangedEvent with @EventListener.

Content changes

A part of a screen that shows other content in its place, the article of a documentation page when another page of the same screen opens, keeps what it shows until the next content is read: it never collapses to nothing for a frame. motion.content-change says how the new content replaces the old one:

spring:
  flutter:
    theme:
      motion:
        content-change: { type: fade-up, duration: 220ms, curve: ease-out }

With morph, stagger is how much later each line starts than the one before it (30ms by default), and delay how long the page waits, blank, before its first line (none by default). Give it the duration of text-change, and a ThemeText above the page (breadcrumbs) morphs first, the page follows:

motion:
  text-change: { type: morph, duration: 650ms }
  content-change: { type: morph, duration: 1.2s, stagger: 40ms, delay: 650ms }

The lines start over at most 85 percent of duration, so a long page is done in duration too. MarkdownView and RouteContentView morph; a ContentChange of anything else shows its new content at once.

When another page opens on the same screen (RouteContentView), the screen also goes back to its top, as a browser opens a page: motion.scroll-to-top (400ms ease-out-cubic by default; none jumps, and so does reduced motion):

motion:
  scroll-to-top: { duration: 500ms, curve: ease-in-out }

The new content gives the height; the old one is cut to it while it goes. RouteContentView and MarkdownView.resource change this way. Wrap any other content in ContentChange(id: ..., child: ...): a new id is a change. With reduced motion the content changes at once.

A kind of your own is registered before the application starts (the themes are read at the start, and a kind no one registered stops it with the names that exist):

void main() {
  ContentTransitions.register(
    'scale',
    (child, animation) => ScaleTransition(scale: animation, child: child),
  );
  runApp(SpringApplicationWidget(application: createApplication));
}

The mouse wheel

Flutter moves a scrollable by the wheel's whole step at once: on the web a page jumps 100 pixels or so per notch, which reads as a stutter. motion.wheel-scroll eases every step of the wheel, for every scrollable of the app, with no controller to set:

motion:
  wheel-scroll: { duration: 250ms, speed: 0.8 }

Touch scrolling keeps its physics. A trackpad that the platform reports as wheel steps (the web) is eased too; its steps are small, so it moves almost as before. WheelScrollSmoother does the work, and SpringApp sets it from the active theme.

Inertia

motion.wheel-scroll.inertia gives scrolling some weight, each kind of pointer its own; every one is off (0) by default:

motion:
  wheel-scroll: { duration: 260ms, speed: 0.75, inertia: { mouse: 0.2 } }
Key What it does
mouse Quick wheel steps one after another go further each (0.2: a fifth more each, up to six in a row) and glide longer, so a wheel spun fast crosses a page and a single notch still moves one step
trackpad Once the fingers stop, the page glides on, keeping that share of its last step each frame (0.9). For a trackpad whose system does not glide by itself, such as many on Windows and Linux; macOS does, so leave it 0 there
touch A flick of the finger throws the page further (0.5: half again as far)

Whatever the inertia, a frame a trackpad sends no step in while the fingers move gets the step of the frames before, and the next step is that much shorter: browsers send a step a frame and now and then none, which made the page stop for a frame and jump twice as far in the next.

Durations

motion.durations.<name> are durations with any name you like, for your own animations.

A duration is a number, optional spaces, and a unit: ms, s, m, h or d (any case). Decimals are fine (1.5s, 0.5d). A plain number is milliseconds. A negative number or another unit is an error. It is the one syntax of every time in a theme: motion, animations, styles, tokens, transition, refresh and timeout.

short, medium and long exist even if you do not write them: 100 ms, 250 ms and 450 ms. Reading another name you did not declare (context.theme.motion has only the names you wrote) is an error that lists the closest name.

AnimatedContainer(
  duration: context.theme.motion.fast,                 // a Duration
  curve: context.theme.motion.curves.emphasized,       // a Curve
  height: expanded ? 200 : 80,
)

Curves

A curve is a name from the table below, or four numbers for a cubic curve (the same as CSS cubic-bezier). Four numbers are written as a YAML list or as one quoted text.

spring:
  flutter:
    theme:
      motion:
        curves:
          standard: '0.2, 0, 0, 1'
          bounce: bounce-out
          snap: [0.4, 0, 0.2, 1]

Names are written in kebab case; easeIn and ease_in also work.

Curve What it feels like
linear Constant speed
ease Starts slowly, speeds up, ends slowly (the CSS ease)
ease-in Starts slowly
ease-out Ends slowly
ease-in-out Starts and ends slowly
fast-out-slow-in Quick start, long gentle end (Material's classic curve)
decelerate Fast start that slows down in a smooth way
standard Material 3's standard easing
standard-accelerate Material 3's standard easing for things that leave
standard-decelerate Material 3's standard easing for things that arrive
emphasized A strong ease: 0.2, 0, 0, 1
emphasized-accelerate Emphasized, for things that leave
emphasized-decelerate Emphasized, for things that arrive
ease-in-sine, ease-out-sine, ease-in-out-sine A very gentle ease
ease-in-cubic, ease-out-cubic, ease-in-out-cubic A stronger ease
ease-in-back, ease-out-back, ease-in-out-back Goes a little backwards first, or overshoots the end
bounce-in, bounce-out, bounce-in-out Bounces like a ball
elastic-in, elastic-out, elastic-in-out Springs like a rubber band

Anything else is an error that lists these names. A curve you have not declared in motion.curves is Material's standard easing when read with SpringTheme.of(context).curve(name); the generated context.theme.motion.curves.<name> exists only for names you declare.

Animations

animations.<name> is a named animation: the time of one run, its curve and what happens at the end.

repeat What happens at the end
none Plays once and stays at the end
loop Starts again from the beginning, for ever
reverse Plays back and forth, for ever

ThemeAnimation plays one. It owns the controller, repeats as asked, takes a new duration or curve when the theme changes, and gives your builder a progress from 0 to 1 along the curve:

ThemeAnimation(
  context.theme.animations.borderSpin,
  builder: (context, t) =>
      Transform.rotate(angle: t.value * 2 * pi, child: ring),
)

An animation can also move a background image (background.animation: border-spin). Every animation needs a duration; one without it stops the start.

Reduced motion

When the device asks for less motion (MediaQuery.disableAnimations):

A duration read from a token (SpringTheme.of(context).tokenDuration(...)) is the plain duration and is not reduced; use the typed context.theme.motion getters, or check MediaQuery.disableAnimationsOf(context) yourself.

See also