Skip to main content

​
Overview

MotionValue is a class used to track the state and velocity of motion values. It exists outside of React’s render cycle, making it efficient for high-frequency updates like animations and gestures.

​
Import

import { motionValue } from "motion-dom"
// or
import { useMotionValue } from "motion/react"

​
Constructor

class MotionValue<V = any> {
  constructor(init: V, options?: MotionValueOptions)
}

function motionValue<V>(init: V, options?: MotionValueOptions): MotionValue<V>

​
Parameters

​
init
V
required
The initial value
​
options
MotionValueOptions
Optional configuration:
  • owner: Internal owner reference (used by Motion components)

​
Methods

​
get()

Returns the latest state of the MotionValue. 
get(): V
Example: 
const x = motionValue(0)
console.log(x.get()) // 0

​
set()

Sets the state of the MotionValue. 
set(v: V): void
Parameters:
​
v
V
required
The new value to set
Example: 
const x = motionValue(0)
x.set(100)

​
jump()

Set the state of the MotionValue, stopping any active animations, effects, and resetting velocity to 0. 
jump(v: V, endAnimation?: boolean): void
Parameters:
​
v
V
required
The new value to set
​
endAnimation
boolean
default:"true"
Whether to stop active animations
Example: 
const x = motionValue(0)
x.jump(100) // Immediately jumps to 100, stops animations

​
on()

Subscribe to MotionValue events. 
on<EventName extends keyof MotionValueEventCallbacks<V>>(
  eventName: EventName,
  callback: MotionValueEventCallbacks<V>[EventName]
): () => void
Events:
  • "change": Fired when the value changes
  • "animationStart": Fired when an animation starts
  • "animationComplete": Fired when an animation completes
  • "animationCancel": Fired when an animation is cancelled
  • "destroy": Fired when the MotionValue is destroyed
Returns: Unsubscribe function Example: 
const x = motionValue(0)

const unsubscribe = x.on("change", (latest) => {
  console.log("x changed to", latest)
})

// Later...
unsubscribe()
React Usage: 
import { useEffect } from "react"
import { useMotionValue } from "motion/react"

export function Component() {
  const x = useMotionValue(0)

  useEffect(() => {
    return x.on("change", (latest) => {
      console.log("x:", latest)
    })
  }, [])

  return <motion.div style={{ x }} />
}

​
getPrevious()

Returns the previous state of the MotionValue. 
getPrevious(): V | undefined
Example: 
const x = motionValue(0)
x.set(100)
console.log(x.getPrevious()) // 0

​
getVelocity()

Returns the latest velocity of the MotionValue. Returns 0 if the state is non-numerical. 
getVelocity(): number
Example: 
const x = motionValue(0)
animate(x, 100)
console.log(x.getVelocity()) // e.g., 250 (pixels per second)

​
isAnimating()

Returns true if this value is currently animating. 
isAnimating(): boolean
Example: 
const x = motionValue(0)
animate(x, 100)
console.log(x.isAnimating()) // true

​
stop()

Stop the currently active animation. 
stop(): void
Example: 
const x = motionValue(0)
const animation = animate(x, 100, { duration: 2 })

// Stop after 1 second
setTimeout(() => x.stop(), 1000)

​
destroy()

Destroy and clean up subscribers to this MotionValue. 
destroy(): void
Example: 
const x = motionValue(0)
// ... use the value
x.destroy()
Note: The useMotionValue hook automatically handles cleanup. Only call destroy() if you manually created a MotionValue via the motionValue function.

​
Properties

​
updatedAt

The time the MotionValue was last updated (in milliseconds). 
updatedAt: number

​
Usage

​
Creating Motion Values

In React: 
import { useMotionValue } from "motion/react"

const x = useMotionValue(0)
In Vanilla JS: 
import { motionValue } from "motion-dom"

const x = motionValue(0)

​
Subscribing to Changes

Listen for value updates: 
const x = motionValue(0)

const unsubscribe = x.on("change", (latest) => {
  console.log("Value:", latest)
})

x.set(100) // Logs: "Value: 100"

unsubscribe()

​
Animation Events

Track animation lifecycle: 
import { motionValue, animate } from "motion-dom"

const x = motionValue(0)

x.on("animationStart", () => console.log("Started"))
x.on("animationComplete", () => console.log("Completed"))
x.on("animationCancel", () => console.log("Cancelled"))

animate(x, 100)

​
Manual Velocity Control

Set velocity explicitly: 
const x = motionValue(0)

// Set with velocity
x.setWithVelocity(0, 100, 16.67) // prev, current, delta (ms)

​
Stopping Animations

const x = motionValue(0)
animate(x, 100, { duration: 2 })

if (x.isAnimating()) {
  x.stop()
}

​
Jumping to Values

Instantly set a value without animation: 
const x = motionValue(0)
animate(x, 100) // Start animation
x.jump(50) // Immediately jump to 50, cancel animation

​
Lifecycle

​
Automatic Cleanup (React)

When using useMotionValue, cleanup is automatic: 
function Component() {
  const x = useMotionValue(0)
  // No cleanup needed - handled automatically
  return <motion.div style={{ x }} />
}

​
Manual Cleanup (Vanilla JS)

When creating values manually, clean up when done: 
const x = motionValue(0)

// ... use the value

// When finished:
x.destroy()

​
Performance

  • Motion values exist outside React’s render cycle
  • Updates don’t trigger component re-renders
  • Velocity is tracked automatically for numerical values
  • Listeners are efficiently managed and cleaned up

​
Notes

  • Motion values can hold any type of value (numbers, strings, colors, etc.)
  • Velocity tracking only works for numerical values
  • When all "change" listeners are removed, active animations are automatically stopped
  • Motion values maintain a dependency graph for transformed values
  • Maximum velocity delta is 30ms - older updates return velocity of 0

Build docs developers (and LLMs) love

Get started for freeTalk to us