animate
A function to manually start and control animations
animate()
is used to manually start and control animations. It will dynamically use hardware-accelerated animations for the best performance whenever possible.
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 gradients - CSS variables
- SVG paths
- Single values
- Motion values
- Animation sequences
- Anything!
#Usage
#Import
Import animate
from "framer-motion"
:
// Miniimport { animate } from "framer-motion/dom/mini"
// Hybridimport { animate } from "framer-motion/dom"
Note: React users are recommended, in most instances, to use animate
via useAnimate
for composable animations scoped to your component.
#Animate HTML/SVG elements
animate
can accept element(s) and DOM selectors.
// Element(s)const box = document.getElementById("box")
animate(box, { opacity: 0 }, { duration: 0.5 })
// Selectorsanimate("div", { x: [0, 100] }, { type: "spring" })
When possible, animations on DOM elements will be hardware accelerated.
#Animate a single value
By passing a to
and from
value, animate
will output the latest values to the provided onUpdate
callback.
// Numbersanimate(0, 100, { onUpdate: latest => console.log(latest)})
// Colors etcanimate("#fff", "#000", { duration: 2 onUpdate: latest => console.log(latest)})
#Animate a MotionValue
By passing animate
a MotionValue
, it'll be automatically updated with the latest values.
const x = motionValue(0)
animate(x, 200, { duration: 0.5 })
#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:
const values = { x: 100, color: "#f00"}
animate(values, { x: 200, color: "#00f" })
Any object can be animated, for instance an Object3D
from Three.js:
const camera = new THREE.Camera()
animate(camera.rotation, { y: 360 }, { duration: 10 })
#Animate sequences
The hybrid animate
can also accept complex animation sequences.
const sequence = []
animate(sequence)
A sequence is an array of DOM and/or MotionValue
animate
definitions.
const progress = useMotionValue(0)
const sequence = [ ["ul", { opacity: 1 }, { duration: 0.5 }], [progress, 100, { ease: "easeInOut" }]]
Each definition will, by default, play one after the other.
const sequence = [ ["ul", { opacity: 1 }, { duration: 0.5 }], ["li", { x: [-100, 0] }, { delay: stagger(0.1) }]]
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.
const sequence = [ ["ul", { opacity: 1 }], ["li", { x: [-100, 0] }, { at: 1 }]]
Each segment can accept all Framer Motion transition options to control the duration and other animation settings of that segment.
const sequence = [ ["ul", { opacity: 1 }, { duration: 1 }]]
Both type: "keyframes"
and type: "spring"
transitions are supported.
It's also possible to override transitions on a per-value basis.
const sequence = [ [ "ul", { opacity: 1, x: 100 }, { duration: 1, x: { duration: 2 }} ]]
Sequence durations are automatically calculated, but it's possible to pass animation options to change playback:
animate(sequence, { duration: 10 })
Any value supported by animate
can be animated in sequences, mixing HTML & SVGs, motion values and objects in the same animation:
const color = motionValue("rgba(255, 0, 0, 1)")const box = new THREE.BoxGeometry()
const sequence = [ ["li", { x: 100 }], [box.position, { y: 10 }], [color, "#444"]]
#Stagger
When animating more than one element, it's possible to stagger animations by passing the stagger
function to delay
.
import { stagger, animate } from "framer-motion"
animate(".item", { x: 300 }, { delay: stagger(0.1) })
#Options
animate()
supports all of Framer Motion's transition options.
Additionally, it accepts these options:
#type: string | spring
type
decides the type of animation to use.
Mini animate
can either animate with the default keyframes animation, or explicitly import spring
from Framer Motion.
import { animate } from "framer-motion/dom/mini"import { spring } from "framer-motion/dom"
animate( element, { transform: "translateX(100px)" }, { type: spring, stiffness: 300 })
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.
import { animate } from "framer-motion/dom"
animate( element, { transform: "translateX(100px)" }, { type: "spring", stiffness: 300 })
#at: string | number
Note: Animation sequences only.
const sequence = [ ["ul", { opacity: 1 }], ["li", { x: [-100, 0] }, { at: 1 }]]
By default, animation definitions within a sequence will play one after the other. By passing at
to a definition's options, this behaviour can be changed.
Pass a number to define a specific time:
const sequence = [ ["nav", { opacity: 1 }], // This will start 0.5 from the start of the whole timeline: ["nav", { x: 100 }, { at: 0.5 }],]
Pass a string starting with +
or -
to start relative to the end of the previous animation:
const sequence = [ ["nav", { opacity: 1 }], // This will start 0.5 seconds after the previous animation: ["nav", { x: 100 }, { at: "+0.5" }], // This will start 0.2 seconds before the end of the previous animation: ["nav li", { opacity: 1 }, { at: "-0.2" }],]
Pass "<"
to start at the same time as the previous segment:
const sequence = [ ["nav", { x: 100 }, { duration: 1 }], // This will start at the same time as the x: 100 animation ["li", { opacity: 1 }, { at: "<" }],]
Or pass a label name to start at the same point as the original label definition:
const sequence = [ ["nav", { x: 100 }, { duration: 1 }], "my-label", ["li", { opacity: 1 }], // my-label was defined at 1 second ["a", { scale: 1.2 }, { at: "my-label" }],]
#onUpdate: (latest) => void
Note: For single value and MotionValue
animations only.
A function that's provided the latest animation values.
animate("#fff", "#000", { duration: 2 onUpdate: latest => console.log(latest)})
#Controls
animate()
returns the following animation controls:
#duration: number
Returns the duration of the animation.
This is the duration of a single iteration of the animation, without delay or repeat options.
const animation = animate(x, 100, { duration: 1, repeat: 2 })
const { duration } = animation // 1
#time: number
Gets and sets the current time of the animation.
const animation = animate(x, 100, { duration: 1 })
// Set animation time to 0.5 secondsanimation.time = 0.5
// Get animation timeconsole.log(animation.time) // 0.5
#then(): Promise
Provide a function to run when the animation is finished.
This allows the animation
to be await
ed.
const animation = animate(0, 100)
// Callbackanimation.then(() => { console.log("Animation complete!")})
// Asyncawait animationconsole.log("Animation complete!")
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(): void
Pause an animation.
animation.pause()
#play(): void
Play an animation.
- If the animation is paused, it will resume from its current
time
. - If the animation has finished, the animation will restart.
animation.pause()
// Will resume from 1 secondanimation.time = 1animation.play()
// Will play from startawait animationanimation.play()
#stop(): void
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.
animation.stop()
#complete(): void
Immediately completes the animation, running it to the end state.
animation.complete()
#cancel(): void
Cancels the animation, running it to the initial state.
animation.cancel()
#speed: number
Gets and sets the playback speed of the animation.
// Normal speedanimation.speed = 1
// Half speedanimation.speed = 0.5
// Double speedanimation.speed = 2
// Reverseanimation.speed = -1