animate
A function to manually start and control animations
animate()
is used to manually start and control animations.
It can animate:
- Numbers, colors, strings
MotionValue
s- HTML/SVG elements
Imported alone, it weighs around 15.5kb
. When used in conjunction with the motion component
there is around 1kb
added bundlesize.
#Usage
#Import
Import animate
from "framer-motion"
:
// Reactimport { animate } from "framer-motion"
// Universalimport { animate } from "framer-motion/dom"
Note: React users are recommended, in most instances, to use animate
via useAnimate
for composable animations.
#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 })
#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 sequences
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 })
#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:
#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