Transition - Motion

Overview

The Transition type defines how animations move from one state to another. It controls timing, easing, animation type, and orchestration of child animations.

Import

import type { Transition } from "motion/react"

Type Definition

type Transition<V = any> =
  | ValueAnimationTransition<V>
  | TransitionWithValueOverrides<V>

A transition can be either a single configuration applied to all properties, or an object with per-property overrides.

Core Properties

Animation Type

type

AnimationGeneratorType

The type of animation:

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

Timing

duration

number

Duration in seconds:

Default: 0.3 for tween
Default: 0.8 for keyframes
Springs use calculated duration or custom duration

delay

number

Delay before animation starts, in seconds. Default: 0

elapsed

number

Time already elapsed in the animation, in seconds. Default: 0

Easing

ease

Easing or Easing[]

Easing function or array of easing functions. Can be:

Named easing: "linear", "easeIn", "easeOut", "easeInOut", "circIn", etc.
Cubic bezier: [0.17, 0.67, 0.83, 0.67]
Custom function: (t: number) => number
Array for keyframes (one per segment)

times

number[]

Array of 0-1 values defining when each keyframe occurs. Must match keyframe count.

Spring Properties

Physics-Based

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.

Duration-Based

duration

number

default:"0.3"

For springs, this overrides physics calculations to create a duration-based spring.

bounce

number

default:"0.25"

Bounciness from 0-1. Only used with duration-based springs. Higher = more bouncy.

visualDuration

number

Time for the bulk of the transition, with “bouncy” part happening after.

Velocity

velocity

number

default:"0"

Initial velocity of the animation.

restSpeed

number

default:"0.01"

End animation if absolute speed drops below this value.

restDelta

number

default:"0.01"

End animation if distance is below this value.

Inertia Properties

power

number

default:"0.8"

Higher power equals further target.

timeConstant

number

default:"700"

Adjusts duration of deceleration.

modifyTarget

(v: number) => number

Modify automatically-calculated target. Useful for snapping to grid.

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 min/max.

bounceDamping

number

default:"10"

Damping of bounce spring when hitting min/max.

Repeat Properties

repeat

number

default:"0"

Number of times to repeat. Set to Infinity for perpetual repeating.

repeatType

string

default:"loop"

How to repeat:

"loop": Restart from beginning
"reverse": Alternate between forward and backward
"mirror": Switch from and to values

repeatDelay

number

default:"0"

Duration to wait between repeats, in seconds.

Orchestration Properties

when

false | beforeChildren or afterChildren

default:"false"

Relationship to children:

false: Animate with children simultaneously
"beforeChildren": Finish before children start
"afterChildren": Start after children finish

delayChildren

number or DynamicOption<number>

default:"0"

Delay before children animations start, in seconds.

staggerChildren

number

default:"0"

Stagger delay between each child, in seconds. ⚠️ Deprecated: use delayChildren: stagger(interval)

staggerDirection

1 or -1

default:"1"

Direction of stagger. ⚠️ Deprecated: use delayChildren: stagger(interval, { from: 'last' })

Lifecycle Callbacks

onUpdate

(latest: V) => void

Called every animation frame with the latest animated 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 manually stopped.

Per-Property Overrides

Define different transitions for specific properties:

interface TransitionWithValueOverrides<V> extends ValueAnimationTransition<V> {
  // Per-property transitions
  [propertyName: string]: ValueTransition | undefined
  
  // Special overrides
  default?: ValueTransition
  layout?: ValueTransition
}

default

ValueTransition

Default transition for properties without specific overrides.

layout

ValueTransition

Transition specifically for layout animations.

Examples

Basic Tween

const transition: Transition = {
  duration: 0.5,
  ease: "easeOut"
}

<motion.div
  animate={{ x: 100 }}
  transition={transition}
/>

Spring Animation

const transition: Transition = {
  type: "spring",
  stiffness: 300,
  damping: 20
}

<motion.div
  animate={{ scale: 1.2 }}
  transition={transition}
/>

Duration-Based Spring

const transition: Transition = {
  type: "spring",
  duration: 0.6,
  bounce: 0.3
}

Keyframe Animation

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

<motion.div
  animate={{ rotate: [0, 90, 0] }}
  transition={transition}
/>

Infinite Loop

const transition: Transition = {
  repeat: Infinity,
  repeatType: "reverse",
  duration: 2
}

<motion.div
  animate={{ rotate: 360 }}
  transition={transition}
/>

Per-Property Transitions

const transition: Transition = {
  default: { duration: 0.3 },
  opacity: { 
    duration: 0.5,
    ease: "easeOut" 
  },
  scale: {
    type: "spring",
    stiffness: 300,
    damping: 20
  }
}

<motion.div
  animate={{ opacity: 1, scale: 1.2, x: 100 }}
  transition={transition}
/>

Orchestrating Children

const transition: Transition = {
  when: "beforeChildren",
  delayChildren: 0.3,
  staggerChildren: 0.1
}

<motion.div
  animate="visible"
  transition={transition}
>
  <motion.div />  {/* Delays 0.3s */}
  <motion.div />  {/* Delays 0.4s */}
  <motion.div />  {/* Delays 0.5s */}
</motion.div>

Layout Animation

const transition: Transition = {
  layout: {
    type: "spring",
    stiffness: 400,
    damping: 30
  },
  opacity: {
    duration: 0.2
  }
}

<motion.div
  layout
  transition={transition}
/>

With Callbacks

const transition: Transition = {
  duration: 1,
  onUpdate: (latest) => {
    console.log("Current value:", latest)
  },
  onComplete: () => {
    console.log("Animation finished!")
  }
}

Inertia Animation

const transition: Transition = {
  type: "inertia",
  velocity: 500,
  power: 0.8,
  timeConstant: 700,
  modifyTarget: (target) => Math.round(target / 100) * 100
}

Type Helpers

ValueAnimationTransition

Base transition type with all options:

interface ValueAnimationTransition<V = any>
  extends ValueTransition,
    AnimationPlaybackLifecycles<V> {
  // All transition properties
}

DynamicOption

Create dynamic values based on element index:

type DynamicOption<T> = (index: number, total: number) => T

// Usage
delayChildren: (i, total) => i * 0.1

Transition Inheritance

inherit

boolean

default:"false"

Whether this transition should merge with parent transition (shallow merge, inner keys win).

// Parent transition
<motion.div transition={{ duration: 1 }">
  {/* Child inherits duration but overrides type */}
  <motion.div 
    transition={{ type: "spring", inherit: true }}
  />
</motion.div>

AnimationOptions

Full animation options reference

Variants

Variant definitions

Easing

Easing function types

Spring Guide

Spring animation guide

Components

Animation

Motion Values

Gestures

Scroll

Layout

Utilities

Types

​Overview

​Import

​Type Definition

​Core Properties

​Animation Type

​Timing

​Easing

​Spring Properties

​Physics-Based

​Duration-Based

​Velocity

​Inertia Properties

​Repeat Properties

​Orchestration Properties

​Lifecycle Callbacks

​Per-Property Overrides

​Examples

​Basic Tween

​Spring Animation

​Duration-Based Spring

​Keyframe Animation

​Infinite Loop

​Per-Property Transitions

​Orchestrating Children

​Layout Animation

​With Callbacks

​Inertia Animation

​Type Helpers

​ValueAnimationTransition

​DynamicOption

​Transition Inheritance

​Related Types

AnimationOptions

Variants

Easing

Spring Guide

Build docs developers (and LLMs) love

Overview

Import

Type Definition

Core Properties

Animation Type

Timing

Easing

Spring Properties

Physics-Based

Duration-Based

Velocity

Inertia Properties

Repeat Properties

Orchestration Properties

Lifecycle Callbacks

Per-Property Overrides

Examples

Basic Tween

Spring Animation

Duration-Based Spring

Keyframe Animation

Infinite Loop

Per-Property Transitions

Orchestrating Children

Layout Animation

With Callbacks

Inertia Animation

Type Helpers

ValueAnimationTransition

DynamicOption

Transition Inheritance

Related Types