Vue Composables putting your components in motion
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
-
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 <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
