Vue Composables putting your components in motion. ALWAYS use when writing code importing "@vueuse/motion". Consult for debugging, best practices, or modifying @vueuse/motion, vueuse/motion, vueuse motion, motion.
@vueuse/motionVue Composables putting your components in motion
Version: 3.0.3 (Mar 2025) Deps: @vueuse/core@^13.0.0, @vueuse/shared@^13.0.0, defu@^6.1.4, framesync@^6.1.2, popmotion@^11.0.5, style-value-types@^5.1.2 Tags: beta: 2.0.0-beta.29 (May 2023), latest: 3.0.3 (Mar 2025)
References: Docs — API reference, guides
This section documents version-specific API changes — prioritize recent major/minor releases.
BREAKING: ESM-only — @vueuse/motion v3.0.0 dropped CommonJS (CJS) support, the package is now ESM-only source
NEW: VueUse v13 support — updated dependencies to support the latest VueUse features in v3.0.0 source
NEW: <Motion> component — declarative component for animations, offering better SSR and MDC support since v2.2.0 source
NEW: <MotionGroup> component — renderless component introduced in v2.2.0 to apply motion configurations to all child elements source
NEW: duration and delay shorthand props — support for setting transition timing directly on elements/components since v2.2.0 source
BREAKING: Drop Vue 2 support — v2.0.0 and above exclusively support Vue 3 source
NEW: Full SSR support — significantly improved server-side rendering compatibility for both components and directives in v2.0.0 source
NEW: kebab-case directive support — v-motion-initial and other directive variants now support kebab-case since v2.1.0 source
NEW: useMotionFeatures export — this composable is now exported for manual feature registration since v2.2.6 source
NEW: useMotion dynamic keys — support for dynamic variant keys when calling .apply() and other methods since v2.1.0 source
NEW: reactive-style and reactive-transform — specialized composables for direct style and transform manipulation since v2.0.0 source
NEW: MotionPlugin types — enhanced TypeScript definitions for the main Vue plugin in v2.2.5 source
BREAKING: onComplete triggers — fixed in v2.2.0 to trigger after each property animation completes instead of only once source
NEW: unref directive bindings — directives now unref initial bindings, supporting refs within objects since v2.0.0 source
Also changed: visibilityOnce variant new v2.0.0 · useSpring documentation update v2.2.0 · preset mutation fix v2.2.0 · useMotions dynamic keys v2.1.0 · useMotionVariants internal updates v2.0.0
useMotions() at the top level of setup because properties are registered after the script execution; access them via the returned object within methods or hooks to ensure reactivity source// Preferred
const motions = useMotions()
const play = () => motions.myElement?.variant.value = 'play'
// Avoid
const { myElement } = useMotions()
Use camelCase for visibility variants in Nuxt 3 templates (e.g., visibleOnce) rather than kebab-case (visible-once) to ensure proper directive resolution and avoid warnings source
Prefer the <Motion> component over the v-motion directive for projects requiring robust SSR, as it handles initial state style injection more reliably for SEO and UX source
Define custom directives in the MotionPlugin configuration to create reusable animation presets that can be applied consistently via v-motion-[name] across the application source
Use <MotionGroup> to apply a single animation configuration or preset to multiple child elements, significantly reducing template boilerplate and improving maintainability source
Map the leave helper from the motion instance to the Vue <transition> element's @leave event to perform manual and synchronized exit animations on elements source
const { leave } = useMotion(target, { leave: { opacity: 0 } })
// In template
// <transition @leave="(el, done) => leave(done)">
Always specify an initial variant containing all properties that will be animated to prevent unexpected layout shifts and ensure smooth transitions from a known base state source
Utilize useSpring with useMotionProperties for high-performance, frame-rate independent animations that require physical continuity, such as for interactive gestures source
In Nuxt applications, use runtimeConfig.public.motion.directives to define global custom directives, ensuring they are properly initialized during both client and server rendering source
Pass a reactive reference as the target to useMotion to allow the motion instance to automatically track and apply the current variant to new elements as they are updated source