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:
- 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,
platformincluded ({ type: platform, duration: 250ms, curve: ease-out }). content: a screen comes in asmotion.content-changeshows other content.- Reduced motion on the device makes every transition instant.
- Switching the branches of a shell never animates.
zoomandcupertinowork in any app type with their starter: the iOS slide in aMaterialApp, Material's zoom in aWidgetsApp.
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);
morph: the characters change one after the other from the start of the line, each running through a few glyphs before it settles on the new one;staggeris the delay from one character to the next. By default the wave runs over the whole line, the characters that stay the same too;keep-unchanged: trueleaves those in place, so only the part that changed runs (a breadcrumb whose last part changes).glyphsare the characters it runs through (taken as written,$included),glyph-durationhow long each one shows:
text-change:
type: morph
duration: 650ms
stagger: 14ms
glyphs: '01<>/' # default ▓▒░<>/\|=+*#%&@$?!01
glyph-duration: 30ms # default 40ms
fade: the old text fades out while the new one fades in.none(the default): the new text at once.
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 }
fade: the old content fades out while the new one fades in.fade-up: the same, the new content rising a little.morph: the new content types itself in, line after line from the top, each line's characters running through glyphs astext-change: morphdoes; the old content goes at once. The page has its full height from the first frame: a line whose turn has not come holds its place unseen.none(the default): the new content at once.
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 }
duration: how long a step takes to arrive; steps that come one after the other add up and keep moving.speed: the share of the step, below 1 slower, above faster.none(the default): Flutter's own behavior.inertia: see inertia.
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):
- every duration read through
context.theme.motionisDuration.zero, - a
ThemeAnimationwithrepeat: nonejumps to its end (tis 1);loopandreversestand still at 0, - an animation of zero duration does the same,
ThemeStateschanges values at once,- the background stands still and changes without a fade.
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
- Properties
- Styles and states:
transition: 120ms ease-out - Background:
animation,effectandtransition - Cupertino: iOS page transitions