animate

animate() is used to manually start and control animations. It will dynamically use hardware-accelerated animations for the best performance whenever possible.

It can animate:

• Numbers, colors, strings
• MotionValues
• 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":

// React
import { animate } from "framer-motion"

// Universal
import { 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.

// Numbers
animate(0, 100, {
  onUpdate: latest => console.log(latest)
})

// Colors etc
animate("#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 })

// Selectors
animate("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) })

#Inertia

animate() does support type: "inertia" animations, but note that currently an arbitrary target value must still be supplied:

animate(x, 100, { type: "inertia", velocity: 100 })

#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 seconds
animation.time = 0.5

// Get animation time
console.log(animation.time) // 0.5

#then(): Promise

Provide a function to run when the animation is finished.

This allows the animation to be awaited.

const animation = animate(0, 100)

// Callback
animation.then(() => {
  console.log("Animation complete!")
})

// Async
await animation
console.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 second
animation.time = 1
animation.play()

// Will play from start
await animation
animation.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 speed
animation.speed = 1

// Half speed
animation.speed = 0.5

// Double speed
animation.speed = 2

// Reverse
animation.speed = -1