animate
animate()
is used to start and manually control animations.
It comes in two sizes, mini (2.5kb) and hybrid (18kb).
Mini
The mini animate
function can animate HTML and SVG styles. It's built on the Web Animations API (WAAPI) to deliver hardware accelerated animations for a tiny bundlesize.
Hybrid
In addition to running animations via WAAPI, the 17kb hybrid animate
function also includes a powerful JavaScript engine capable of animating:
Independent transforms
More styles, like
mask-image
and gradientsCSS variables
SVG paths
Single values
Animation sequences
Anything!
Usage
animate
can be imported from "motion"
:
HTML & SVG
Both versions of animate
are capable of animating HTML and SVG styles by passing elements directly, or via selectors.
Transforms
The hybrid version of animate
can animate every transform axis independently:
Translate:
x
,y
,z
Scale:
scale
,scaleX
,scaleY
Rotate:
rotate
,rotateX
,rotateY
,rotateZ
Skew:
skew
,skewX
,skewY
Perspective:
transformPerspective
CSS variables
Hybrid animate
can animate CSS variables in every browser:
Mini animate
can only animate registered CSS properties in modern browsers.
SVG paths
The hybrid animate
function can perform line drawing animations with most SVG elements using three special properties: pathLength
, pathSpacing
and pathOffset
.
All three are set as a progress value between 0
and 1
, 1
representing the total length of the path.
Path animations are compatible with circle
, ellipse
, line
, path
, polygon
, polyline
and rect
elements.
Single values
By passing a to
and from
value, the hybrid animate
will output the latest values to the provided onUpdate
callback.
Motion values
By passing hybrid animate
a motion value, it'll be automatically updated with the latest values.
Objects
Objects can be animated much in the same way as HTML & SVG elements.
Any object can be animated, for instance an Object3D
from Three.js:
Timeline sequencing
The hybrid animate
function can also accept complex animation sequences.
A sequence is an array of animate
definitions:
Each definition will, by default, play one after the other.
It's possible to change when a segment will play by passing an at
option, which can be either an absolute time, relative time, or label.
Each segment can accept all animate
options to control the duration and other animation settings of that segment.
Both type: "keyframes"
and type: "spring"
transitions are supported.
It's also possible to override transitions for each value individually.
Sequence durations are automatically calculated, but it's possible to pass animation options to change playback:
Any value supported by animate
can be animated in sequences, mixing HTML & SVGs, motion values and objects in the same animation:
Stagger
When animating more than one element, it's possible to stagger animations by passing the stagger
function to delay
.
Options
Animations can be configured with transition options. By default, provided options will affect every animating value.
By providing named transitions, these can be overridden on a per-value basis:
type
type
decides the type of animation to use.
Mini animate
can either animate with the default keyframes animation, or spring
:
Hybrid animate
has all animation types built-in, and can be set to "tween"
, "spring"
or "inertia"
.
Tween animations are set with a duration and an easing curve.
Spring animations are either physics-based or duration-based.
Physics-based spring animations are set via stiffness
, damping
and mass
, and these incorporate the velocity of any existing gestures or animations for natural feedback.
Duration-based spring animations are set via a duration
and bounce
. These don't incorporate velocity but are easier to understand.
Inertia animations decelerate a value based on its initial velocity, usually used to implement inertial scrolling.
Tween
duration
Default: 0.3
(or 0.8
if multiple keyframes are defined)
The duration of the animation. Can also be used for "spring"
animations when bounce
is also set.
ease
The easing function to use with tween animations. Accepts:
Easing function name. E.g
"linear"
An array of four numbers to define a cubic bezier curve. E.g
[.17,.67,.83,.67]
A JavaScript easing function, that accepts and returns a value
0
-1
.
These are the available easing function names:
"linear"
"easeIn"
,"easeOut"
,"easeInOut"
"circIn"
,"circOut"
,"circInOut"
"backIn"
,"backOut"
,"backInOut"
"anticipate"
When animating keyframes, ease
can optionally be set as an array of easing functions to set different easings between each value:
times
When animating multiple keyframes, times
can be used to adjust the position of each keyframe throughout the animation.
Each value in times
is a value between 0
and 1
, representing the start and end of the animation.
There must be the same number of times
as there are keyframes. Defaults to an array of evenly-spread durations.
Spring
bounce
Default: 0.25
bounce
determines the "bounciness" of a spring animation.
0
is no bounce, and 1
is extremely bouncy.
Note: bounce
and duration
will be overridden if stiffness
, damping
or mass
are set.
visualDuration
If visualDuration
is set, this will override duration
.
The visual duration is a time, set in seconds, that the animation will take to visually appear to reach its target.
In other words, the bulk of the transition will occur before this time, and the "bouncy bit" will mostly happen after.
This makes it easier to edit a spring, as well as visually coordinate it with other time-based animations.
damping
Default: 10
Strength of opposing force. If set to 0, spring will oscillate indefinitely.
mass
Default: 1
Mass of the moving object. Higher values will result in more lethargic movement.
stiffness
Default: 1
Stiffness of the spring. Higher values will create more sudden movement.
velocity
Default: Current value velocity
The initial velocity of the spring.
restSpeed
Default: 0.1
End animation if absolute speed (in units per second) drops below this value and delta is smaller than restDelta
.
restDelta
Default: 0.01
End animation if distance is below this value and speed is below restSpeed
. When animation ends, the spring will end.
Orchestration
delay
Default: 0
Delay the animation by this duration (in seconds).
By setting delay
to a negative value, the animation will start that long into the animation. For instance to start 1 second in, delay
can be set to -1
.
repeat
Default: 0
The number of times to repeat the transition. Set to Infinity
for perpetual animation.
repeatType
Default: "loop"
How to repeat the animation. This can be either:
loop
: Repeats the animation from the start.reverse
: Alternates between forward and backwards playback.mirror
: Switches animation origin and target on each iteration.
repeatDelay
Default: 0
Note: Not available in animate
mini.
When repeating an animation, repeatDelay
will set the duration of the time to wait, in seconds, between each repetition.
at
When defining animations as part of a larger sequence, each definition will start one after the other:
By passing at
, this behaviour can be changed.
Pass a number to define a specific time:
Pass a string starting with +
or -
to start relative to the end of the previous animation:
Pass "<"
to start at the same time as the previous segment:
Or pass a label name to start at the same point as the original label definition:
onUpdate
A function that's provided the latest animation values.
Note: Currently for single value and motion value animations only.
Controls
animate()
returns animation playback controls. These can be used to pause, play, cancel, change playback speed and more.
duration
Returns the duration of the animation.
This is the duration of a single iteration of the animation, without delay or repeat options. It is read-only.
time
Gets and sets the current time of the animation.
speed
Gets and sets the current playback speed of the animation.
1
is normal rate.0.5
is half rate.2
doubles the playback rate.-1
reverses playback.
then()
A Promise
-like API that resolves when the animation finishes:
Note: When an animation finishes, a new Promise
is created. If the animation is then replayed via the play()
method, any old callbacks won't fire again.
pause()
Pauses the animation until resumed with play()
.
play()
Plays an animation.
If an animation is paused, it will resume from its current
time
.If an animation has finished, it will restart.
complete()
Immediately completes the animation, running it to the end state.
cancel()
Cancels the animation, reverting it to the initial state.
stop()
Stops the animation.
Any values being animated via the Web Animations API will be committed to the element via style
.
Stopped animations cannot be restarted.
Examples
Simple animation
Easing options
Stagger
Spring
SVG loading spinner
A Motion+ membership will give you early access to features & content, access to our private Discord, and more.
It's a one-time fee that grants lifetime access. No subscription necessary!