Skip to main content

​
Overview

The AnimationOptions type defines configuration options for animations in Motion. It provides control over timing, easing, orchestration, and more.

​
Import

import type { AnimationOptions } from "motion"

​
Type Definition

type AnimationOptions =
  | ValueAnimationWithDynamicDelay & ReduceMotionOption
  | (ValueAnimationWithDynamicDelay &
      ReduceMotionOption &
      StyleTransitions &
      SVGPathTransitions &
      SVGTransitions &
      VariableTransitions & {
        default?: ValueTransition
        layout?: ValueTransition
      })

​
Core Options

​
Timing

​
duration
number
default:"0.3"
Total duration of the animation in seconds.
​
delay
number or DynamicOption<number>
default:"0"
Delay before animation starts in seconds. Can be a function for staggered animations.
​
elapsed
number
default:"0"
Duration of time already elapsed in the animation.

​
Easing

​
ease
Easing or Easing[]
Easing function or array of easing functions for keyframe animations.
​
times
number[]
Array of numbers between 0 and 1 defining when each keyframe occurs. Must match keyframe count.

​
Animation Type

​
type
AnimationGeneratorType
default:"tween"
Type of animation:
  • "tween": Duration-based with easing
  • "spring": Physics or duration-based spring
  • "inertia": Decay animation
  • "keyframes": Multi-keyframe animation
  • false: Instant (no animation)

​
Repeat Options

​
repeat
number
default:"0"
Number of times to repeat. Set to Infinity for infinite loops.
​
repeatType
string
default:"loop"
How to repeat the animation:
  • "loop": Restart from beginning
  • "reverse": Alternate direction each time
  • "mirror": Swap from/to values each time
​
repeatDelay
number
default:"0"
Delay between repeats in seconds.

​
Spring Options

When type: "spring":
​
stiffness
number
default:"100"
Spring stiffness. Higher values create more sudden movement.
​
damping
number
default:"10"
Strength of opposing force. Set to 0 for infinite oscillation.
​
mass
number
default:"1"
Mass of the moving object. Higher values result in more lethargic movement.
​
bounce
number
default:"0.25"
Bounciness of the spring (0-1). Used with duration for intuitive spring configuration.
​
visualDuration
number
Time for the visual bulk of the animation to complete. The spring will “bounce” after this.
​
velocity
number
default:"0"
Initial velocity of the animation.
​
restSpeed
number
default:"0.01"
End animation if speed drops below this value.
​
restDelta
number
default:"0.01"
End animation if distance is below this value.

​
Inertia Options

When type: "inertia":
​
power
number
default:"0.8"
Higher power equals further target.
​
timeConstant
number
default:"700"
Affects duration of deceleration.
​
modifyTarget
(v: number) => number
Function to modify the automatically-calculated target. Useful for snapping.
​
min
number
Minimum constraint. Value will bounce against this.
​
max
number
Maximum constraint. Value will bounce against this.
​
bounceStiffness
number
default:"500"
Stiffness of bounce spring when hitting constraints.
​
bounceDamping
number
default:"10"
Damping of bounce spring when hitting constraints.

​
Orchestration Options

​
when
false | beforeChildren or afterChildren
default:"false"
When to animate relative to children:
  • false: Animate with children
  • "beforeChildren": Finish before children start
  • "afterChildren": Start after children finish
​
delayChildren
number or DynamicOption<number>
default:"0"
Delay before starting child animations.
​
staggerChildren
number
default:"0"
Stagger delay between child animations (deprecated: use delayChildren: stagger()).
​
staggerDirection
1 or -1
default:"1"
Direction of stagger (deprecated: use delayChildren: stagger(interval, { from: 'last' })).

​
Lifecycle Callbacks

​
onUpdate
(latest: V) => void
Called on every animation frame with the latest value.
​
onPlay
() => void
Called when animation starts playing.
​
onComplete
() => void
Called when animation completes.
​
onRepeat
() => void
Called each time animation repeats.
​
onStop
() => void
Called when animation is stopped.

​
Accessibility

​
reduceMotion
boolean
Whether to reduce motion for this animation:
  • true: Skip transform/layout animations
  • false: Always animate
  • undefined: Use device preference (default)

​
Per-Property Transitions

Define different transitions for specific properties: 
interface StyleTransitions {
  [K in keyof CSSStyleDeclaration]?: ValueTransition
}

​
Examples

​
Basic Tween

const options: AnimationOptions = {
  duration: 0.5,
  ease: "easeOut"
}

animate(element, { opacity: 1 }, options)

​
Spring Animation

const options: AnimationOptions = {
  type: "spring",
  stiffness: 300,
  damping: 20
}

animate(element, { scale: 1.2 }, options)

​
Duration-Based Spring

const options: AnimationOptions = {
  type: "spring",
  duration: 0.6,
  bounce: 0.3
}

​
Keyframe Animation

const options: AnimationOptions = {
  duration: 2,
  ease: ["easeIn", "easeOut"],
  times: [0, 0.5, 1]
}

animate(element, { opacity: [0, 1, 0] }, options)

​
Repeat Animation

const options: AnimationOptions = {
  repeat: Infinity,
  repeatType: "reverse",
  repeatDelay: 0.5,
  duration: 1
}

​
With Callbacks

const options: AnimationOptions = {
  duration: 1,
  onUpdate: (latest) => console.log(latest),
  onComplete: () => console.log("Done!")
}

​
Staggered Children

const options: AnimationOptions = {
  delayChildren: 0.2,
  staggerChildren: 0.1
}

​
Inertia Animation

const options: AnimationOptions = {
  type: "inertia",
  velocity: 1000,
  min: 0,
  max: 500,
  bounceStiffness: 300
}

​
Per-Property Transitions

const options: AnimationOptions = {
  default: { duration: 0.3 },
  opacity: { duration: 0.5 },
  scale: { 
    type: "spring",
    stiffness: 300 
  }
}

animate(element, { 
  opacity: 1, 
  scale: 1.2 
}, options)

​
Reduced Motion

const options: AnimationOptions = {
  duration: 0.5,
  reduceMotion: true // Skip animation
}

​
Dynamic Delay

const options: AnimationOptions = {
  delay: (i, total) => i * 0.1 // Stagger by index
}

​
Helper Types

​
DynamicOption

Create values based on index: 
type DynamicOption<T> = (index: number, total: number) => T

​
ValueTransition

Base transition configuration: 
interface ValueTransition
  extends AnimationOrchestrationOptions,
    AnimationPlaybackOptions,
    SpringOptions,
    InertiaOptions,
    KeyframeOptions {
  type?: AnimationGeneratorType
  duration?: number
  // ... all options combined
}

Transition

Transition type reference

SpringOptions

Spring animation options

InertiaOptions

Inertia animation options

Easing

Easing function types

Build docs developers (and LLMs) love

Get started for freeTalk to us