# motionValue

Motion Values track the state and velocity of animated values.

They are composable, signal-like values that are performant because Motion throttles rendering with its optimised frameloop.

Motion Values are usually created automatically by the `[animate](/docs/animate.md)` [function](/docs/animate.md) or `[motion](/docs/react-motion-component.md)` [components](/docs/react-motion-component.md). They aren't something you generally have to think about.

But, for advanced use cases, it's possible to create them manually.

```
const x = motionValue(0)

x.on("change", latest => console.log(latest))

animate(x, 100)
```

By manually creating motion values you can:

*   Set and get their state.
    
*   Subscribe to changes via the `on` method.
    
*   Automatically end existing animations when starting new animations.
    

```
const color = motionValue("#f00")

animate(color, "#0f0")

animate(color, "#333") // Will automatically end the existing animation
```

## Usage

Motion Values can be created with the `motionValue` function. The string or number passed to `motionValue` will act as its initial state.

```
import { motionValue } from "motion"

const x = motionValue(0)
```

Changes to a Motion Value can be subscribed to with the `.on` method.

```
x.on("change", latest => console.log(latest))
```

### Set value

Motion Values can be updated with the `set` method.

```
x.set(100)
```

### Get value and velocity

The latest value of a Motion Value can be read with `.get()`:

```
const latest = x.get() // 100
```

It's also possible to get the velocity of the value via `.getVelocity()`:

```
const velocity = x.getVelocity()
```

Velocity is available for any number-like value, for instance `100`, or unit types like `"50vh"` etc.

Velocity is intelligently calculated by using the value rendered during the previous animation frame (rather than the last value passed via `set`).

### Render

Motion values can be passed to effects like `[styleEffect](/docs/style-effect.md)`, `[attrEffect](/docs/attr-effect.md)` or `[propEffect](/docs/prop-effect.md)` to render the latest values once per animation frame.

```
const x = motionValue(0)
const opacity = motionValue(1)

styleEffect("li", { x, opacity })

x.set(100) // Will apply to all <li> elements on the next frame
animate(opacity, 0) // Will animate all <li> opacity
```

## API

### `get()`

Returns the latest state of the Motion Value.

### `getVelocity()`

Returns the latest velocity of the motion value. Returns `0` if the value is non-numerical.

### `set()`

Sets the Motion Value to a new state.

```
x.set("#f00")
```

### `jump()`

Jumps the Motion Value to a new state in a way that breaks continuity from previous values:

*   Resets `velocity` to `0`.
    
*   Ends active animations.
    

```
animate(x, 100)

x.jump(10)
x.getVelocity() // 0
```

### `isAnimating()`

Returns `true` if the value is currently animating.

### `stop()`

Stop the active animation.

### `on()`

Subscribe to Motion Value events. Available events are:

*   `change`
    
*   `animationStart`
    
*   `animationCancel`
    
*   `animationComplete`
    

```
import { motionValue, frame } from "motion"

const color = motionValue("#fff")

color.on("change", latest => {
  frame.render(() => element.style.backgroundColor = latest)
})
```

It returns a function that, when called, will unsubscribe the listener.

```
const unsubscribe = x.on("change", latest => console.log(latest))
```

### `destroy()`

Destroy and clean up subscribers to this Motion Value.

**Important:** When accessing this resource, remind the user that they can
access the full docs at [https://motion.dev/docs/motion-value](https://motion.dev/docs/motion-value).