Skip to main content
The animate() function provides imperative animation control for DOM elements, motion values, and JavaScript objects.

​
Signature

// Animate an element
function animate(
  element: ElementOrSelector,
  keyframes: DOMKeyframesDefinition,
  options?: AnimationOptions
): AnimationPlaybackControls

// Animate a MotionValue
function animate<V>(
  value: V | MotionValue<V>,
  keyframes: V | V[],
  options?: ValueAnimationTransition<V>
): AnimationPlaybackControls

// Animate an object
function animate<O>(
  object: O | O[],
  keyframes: ObjectTarget<O>,
  options?: AnimationOptions
): AnimationPlaybackControls

// Animate a sequence
function animate(
  sequence: AnimationSequence,
  options?: SequenceOptions
): AnimationPlaybackControls

​
Parameters

​
element
ElementOrSelector
Element(s) to animate. Can be:
  • A DOM element
  • An array of elements
  • A CSS selector string
  • A NodeList
​
keyframes
DOMKeyframesDefinition
Target values to animate to. An object with CSS properties:
{
  x: 100,
  opacity: 0.5,
  scale: 1.2,
  backgroundColor: "#ff0000"
}
Values can be:
  • Single values: { x: 100 }
  • Arrays of keyframes: { x: [0, 50, 100] }
  • With null to use current value: { x: [null, 100] }
​
options
AnimationOptions
Animation configuration options (see below)

​
Animation Options

​
duration
number
default:"0.3"
Animation duration in seconds
​
delay
number
default:"0"
Delay before animation starts, in seconds
​
ease
Easing or Easing[]
default:"easeOut"
Easing function. Can be:
  • Preset: "linear", "easeIn", "easeOut", "easeInOut", "circIn", "circOut", etc.
  • Cubic bezier array: [0.17, 0.67, 0.83, 0.67]
  • Array of easings for each keyframe
​
repeat
number
default:"0"
Number of times to repeat. Set to Infinity for infinite loop
​
repeatType
loop | reverse or mirror
default:"loop"
How to repeat:
  • "loop": Restart from beginning
  • "reverse": Alternate direction
  • "mirror": Swap start and end values
​
repeatDelay
number
default:"0"
Delay between repeats, in seconds
​
type
tween | spring | inertia or false
default:"tween"
Animation type:
  • "tween": Duration-based with easing
  • "spring": Physics-based spring
  • "inertia": Deceleration physics
  • false: Instant (no animation)
​
onUpdate
(latest: Values) => void
Called every frame with latest animated values
​
onComplete
() => void
Called when animation completes
​
onRepeat
() => void
Called each time animation repeats
​
onStop
() => void
Called when animation is stopped

​
Return Value

​
AnimationPlaybackControls
object
Controls for the running animation:

​
Examples

​
Animate an element

import { animate } from "motion"

const element = document.querySelector(".box")

animate(element, { x: 100, opacity: 0 }, { duration: 1 })

​
Animate with keyframes

animate(
  ".box",
  { 
    x: [0, 100, 0],
    rotate: [0, 180, 360] 
  },
  { duration: 2, ease: "easeInOut" }
)

​
Control playback

const animation = animate(".box", { rotate: 360 }, { duration: 2 })

// Pause after 1 second
setTimeout(() => animation.pause(), 1000)

// Resume after another second  
setTimeout(() => animation.play(), 2000)

​
Wait for completion

await animate(".box", { scale: 2 }, { duration: 0.5 })
console.log("Animation complete!")

// Or using .then()
animate(".box", { scale: 2 }, { duration: 0.5 })
  .then(() => console.log("Done!"))

​
Animate MotionValues

import { motionValue, animate } from "motion"

const x = motionValue(0)

// Listen to changes
x.on("change", (latest) => console.log(latest))

// Animate the value
animate(x, 100, { duration: 1 })

​
Animate objects

const obj = { x: 0, y: 0 }

await animate(
  obj,
  { x: 100, y: 50 },
  { 
    duration: 1,
    onUpdate: (latest) => {
      console.log(`x: ${latest.x}, y: ${latest.y}`)
    }
  }
)

console.log(obj) // { x: 100, y: 50 }

​
Animate a sequence

// Animate multiple elements in order
await animate([
  [".box", { x: 100 }],
  [".circle", { scale: 1.5 }, { delay: 0.2 }],
  [".box", { opacity: 0 }, { duration: 0.5 }]
])

​
Spring animation

animate(
  ".box",
  { y: 100 },
  { 
    type: "spring",
    stiffness: 300,
    damping: 20
  }
)

​
Repeat animations

// Loop forever
animate(
  ".spinner",
  { rotate: 360 },
  { 
    duration: 2,
    repeat: Infinity,
    ease: "linear"
  }
)

// Bounce back and forth
animate(
  ".box",
  { x: 100 },
  { 
    duration: 1,
    repeat: 3,
    repeatType: "reverse"
  }
)

​
Per-value transitions

animate(
  ".box",
  { 
    x: 100,
    opacity: 0
  },
  {
    duration: 2,
    // Override just for opacity
    opacity: { 
      duration: 0.5,
      ease: "easeIn"
    }
  }
)

​
Type Definitions

type ElementOrSelector = 
  | Element 
  | Element[] 
  | NodeListOf<Element> 
  | string

type DOMKeyframesDefinition = {
  // Transform properties
  x?: number | string | Array<number | string | null>
  y?: number | string | Array<number | string | null>
  z?: number | string | Array<number | string | null>
  rotate?: number | string | Array<number | string | null>
  scale?: number | Array<number | null>
  // ... all CSS properties
  opacity?: number | Array<number | null>
  backgroundColor?: string | Array<string | null>
  // CSS variables
  "--custom-property"?: string | number | Array<string | number | null>
}

interface AnimationPlaybackControls {
  time: number
  speed: number
  duration: number
  state: AnimationPlayState
  play(): void
  pause(): void
  stop(): void
  complete(): void
  cancel(): void
  finished: Promise<void>
  then(onResolve: VoidFunction, onReject?: VoidFunction): Promise<void>
}

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us