The motion Component

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

motion component

An element such as motion.div that renders like the plain tag and accepts animation props (animate, initial, transition).

motion value

An object that holds one animated number (or colour). Changing it updates the element's style without a React re-render.

WAAPI

The Web Animations API: the browser's own animation engine. Motion uses it for transform, opacity, filter, clipPath and backgroundColor.

spring

An animation driven by physics (stiffness, damping) instead of a fixed duration. Phase 9 covers the maths.

hybrid engine

Motion's mix of browser animations (WAAPI) where they can do the job and its own JavaScript loop where they cannot.

keyframes

More than one value for a property, such as x: [0, 100, 50]; the animation passes through each in turn.

1. 1

   Turn the spring into a tween

   In the first example add transition={{ duration: 0.3 }} to the box. Measured: all three tracks last 300 ms with ease-out, and at 170 ms the box is at 120.5 px and rising, and at 300 ms it is at exactly 160, with no overshoot.

2. 2

   Make the spring bouncier

   Add transition={{ type: "spring", bounce: 0.6 }}. Measured: the transform track now lasts 800 ms (it was 500), and at 170 ms the box is at 199.8 px, about 25 percent past its 160 px target; it is back at 158 px at 300 ms and 152 px at 400 ms (it swings below the target before settling). Step through to see it swing.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   The problem this solves: in React, changing state swaps the screen in one frame. CSS transitions can soften a few properties, but they cannot reach height: auto, cannot use spring physics, cannot keep an element on screen after React removes it, and need class names for every state. Hand-written animation code is worse: it fights React's renders. Motion keeps the animation next to the state that causes it.

2. 2

   The component. motion.div (and motion.button, motion.svg, and so on for every HTML and SVG tag) renders the element you expect and adds props: animate is the target, initial is where it starts, transition says how to get there. On the first render the element starts at its animate values and nothing runs (measured: animations at load: 0). initial={false} says the same on purpose; initial={{ opacity: 0 }} makes it animate in. When animate changes, only the values that changed move, from where they are now, so an interrupted move continues from its current value.

3. 3

   Defaults, from the installed source. With no transition, Motion chooses per value. Transform values (x, y, rotate) use a spring with stiffness: 500, damping: 25. scale uses a critically damped spring (stiffness: 550, damping 30, or about 46.9 when the target is 0). Everything else (opacity, colours, height) uses a 0.3 s tween with the curve [0.25, 0.1, 0.35, 1]. A list of more than two keyframes takes 0.8 s. These differ from the explicit spring default (stiffness: 100, damping: 10, Phase 9) that applies when you write type: "spring" yourself.

4. 4

   Two engines. Motion is hybrid. For opacity, clipPath, filter, transform (all of x, y, rotate, scale) and backgroundColor, it hands the animation to the browser as a Web Animation (WAAPI), which can run off the main thread (Phase 6). Springs are sampled once into a linear() curve, which is why the Timeline shows a 500 ms transform track with a long curve. For everything else (height, width, borderRadius) and whenever WAAPI cannot be used, Motion runs its own loop on requestAnimationFrame and writes styles every frame. No browser animation exists then, so the Timeline shows no track.

5. 5

   When WAAPI is skipped. The source refuses WAAPI when the element has an onUpdate callback (there is no way to read a WAAPI value each frame), a transformTemplate, a repeat delay or repeatType: "mirror", a spring with damping: 0, or an inertia animation. Adding onUpdate to a harmless box is a common way to lose compositor animation without noticing.

6. 6

   Motion values. Every animated value is a motion value: a small object holding the current number. useMotionValue(0) makes one, useTransform(x, [0, 200], [0.3, 1]) derives another, and style={{ x, opacity }} binds them to the element. Changing a motion value updates the element's style directly without re-rendering React. The example below calls x.set three times, and React rendered once.

7. 7

   Edge cases. animate={{ height: "auto" }} works: Motion measures the real height first, then animates the number (a layout property, driven from JavaScript, so there is no Timeline track). If the component unmounts mid-animation, the animation stops with the element, with no console warning (measured).

• ↔

  Motion's default springs feel natural, but a spring's end is hard to predict: for exact timing (a 300 ms sync with other things) use duration, which gives a tween.

• You can say which defaults Motion uses for x, scale and opacity

• You can tell from the Timeline whether a Motion animation runs through WAAPI

• You can animate to height: "auto" and say what it costs

• You can drive a value with a motion value and no React state