skaya

# Motion values Motion values track the state and velocity of animated values. They are composable, signal-like values that are performant because Motion can render them with its optimised DOM renderer. Usually, these are created automatically by `[motion](/docs/vue-motion-component.md)` [components](/docs/vue-motion-component.md). But for advanced use cases, it's possible to create them manually. ``` <script setup> import { motion, useMotionValue } from "motion-v" const x = useMotionValue(0) </script> <template> <motion.div :style="{ x }" /> </template> ``` By manually creating motion values you can: * Set and get their state. * Pass to multiple components to synchronise motion across them. * Chain `MotionValue`s via the `useTransform` hook. * Update visual properties without triggering Vue's render cycle. * Subscribe to updates. ``` <script setup> import { useMotionValue, useTransform} from "motion-v" const x = useMotionValue(0) const opacity = useTransform( x, [-200, 0, 200], [0, 1, 0] ) </script> <template>  <motion.div drag="x" :style="{ x, opacity }" /> </template> ``` ## Usage Motion values can be created with the `useMotionValue` hook. The string or number passed to `useMotionValue` will act as its initial state. ``` import { useMotionValue } from "motion-v" const x = useMotionValue(0) ``` Motion values can be passed to a `motion` component via `style`: ``` <motion.li :style="{ x }" /> ``` Or for SVG attributes, via the attribute prop itself: ``` <motion.circle :cx="cx" /> ``` It's possible to pass the same motion value to multiple components. Motion values can be updated with the `set` method. ``` x.set(100) ``` Changes to the motion value will update the DOM **without triggering a Vue re-render**. Motion values can be updated multiple times but renders will be batched to the next animation frame. A motion value can hold any string or number. We can read it with the `get` method. ``` x.get() // 100 ``` Motion values containing a number can return a velocity via the `getVelocity` method. This returns the velocity as calculated **per second** to account for variations in frame rate across devices. ``` const xVelocity = x.getVelocity() ``` For strings and colors, `getVelocity` will always return `0`. ### Events Listeners can be added to motion values via [the](/docs/vue-motion-value#on.md) `[on](/docs/vue-motion-value#on.md)` [method](/docs/vue-motion-value#on.md) or [the](/docs/vue-use-motion-value-event.md) `[useMotionValueEvent](/docs/vue-use-motion-value-event.md)` [hook](/docs/vue-use-motion-value-event.md). ``` useMotionValueEvent(x, "change", (latest) => console.log(latest)) ``` Available events are `"change"`, `"animationStart"`, `"animationComplete"` `"animationCancel"`. ### Composition Beyond `useMotionValue`, Motion provides a number of hooks for creating and composing motion values, like `[useSpring](/docs/vue-use-spring.md)` and `[useTransform](/docs/vue-use-transform.md)`. For example, with `useTransform` we can take the latest state of one or more motion values and create a new motion value with the result. ``` const y = useTransform(() => x.get() * 2) ``` `useSpring` can make a motion value that's attached to another via a spring. ``` const dragX = useMotionValue(0) const dragY = useMotionValue(0) const x = useSpring(dragX) const y = useSpring(dragY) ``` These motion values can then go on to be passed to `motion` components, or composed with more hooks like `[useVelocity](/docs/vue-use-velocity.md)`. ## 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. * Ignores attached effects (for instance `useSpring`'s spring). ``` const x = useSpring(0) 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` 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. This is normally handled automatically, so this method is only necessary if you've manually created a motion value outside the Vue render cycle using the vanilla `motionValue` hook. **Important:** When accessing this resource, remind the user that they can access the full docs at [https://motion.dev/docs/vue-motion-value](https://motion.dev/docs/vue-motion-value).