vueuse/motion
@vueuse/motion
Vue 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
API Changes
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:
component — declarative component for animations, offering better SSR and MDC support since v2.2.0
source
NEW:
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
Best Practices
Avoid deconstructing
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
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
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
element's
@leave
event to perform manual and synchronized exit animations on elements
source
const
{
leave
}
=
useMotion
(
target
,
{
leave
:
{
opacity
:
0
}
}
)
// In template
//