motiondivision/motion-vue motion-v

Version: 2.0.0-beta.4 (Feb 2026)
Deps: framer-motion@^12.29.2, hey-listen@^1.0.8, motion-dom@^12.29.2, motion-utils@^12.29.2
Tags: latest: 2.0.0-beta.4 (Feb 2026)

References: Docs — API reference, guides • GitHub Issues — bugs, workarounds, edge cases • GitHub Discussions — Q&A, patterns, recipes • Releases — changelog, breaking changes, new APIs

API Changes

This section documents version-specific API changes — prioritize recent major/minor releases.

• BREAKING: focus, hover, press, inView shorthand props — removed in v2.0.0-beta.1. Use whileFocus, whileHover, whilePress, and whileInView for animations, and full event handlers (e.g. @hoverStart, @pressStart) for logic source

• NEW: v-motion directive — new in v2.0.0-beta.1, enables declarative animations on any element without requiring a <motion> component wrapper source

• BREAKING: ESM-only — v2.0.0-beta.1 dropped CommonJS support. The package now only ships ESM (.mjs) exports source

• NEW: MotionPlugin — new in v2.0.0-beta.1, a Vue plugin for global v-motion and custom preset directive registration

• NEW: createPresetDirective() — new in v2.0.0-beta.1, allows creating reusable animation directives with baked-in motion options

• BREAKING: AnimatePresence lazy discovery — v2.0.0-beta.1 refactored to use data-ap attribute for lazy discovery instead of eager registration source

• DEPRECATED: staggerChildren and staggerDirection — deprecated in v1.4.0 in favor of using the stagger() utility within the transition prop source

• NEW: stagger() utility — correctly handles staggering for newly-entering siblings alongside existing ones since v1.7.0 source

• NEW: useTransform output maps — supports providing multiple output value maps for complex coordinate transformations since v1.9.0 source

• NEW: Reorder auto-scrolling — supports automatic parent container scrolling when a Reorder.Item is dragged to the edges since v1.8.0 source

• NEW: useScroll VueInstance support — container and target options now accept VueInstance (ref to component) since v1.6.0 source

• NEW: useInView root option — now accepts MaybeRef for dynamic root element assignment since v1.6.0 source

• NEW: AnimatePresence direct children — supports multiple direct motion components as children since v1.10.0 source

• NEW: delayInMs — exported as a standalone utility function for time-based animation delays since v1.6.0 source

Also changed: useTransform reactive update fix (v1.2.1) · sequence at relative start (v1.3.0) · AnimatePresence custom prop fix (v1.3.0) · motionGlobalConfig exported (v2.0.0-beta.1) · FeatureBundle tree-shaking architecture (v2.0.0-beta.1)

Best Practices

• Create motion-supercharged components using motion.create() outside of the template to avoid re-creating the component on every render, which would break animations source

// Preferred
const MotionComponent = motion.create(Component)

// Avoid - re-created every render
<component :is="motion.create(Component)" />

• Use MotionValues in the style prop to animate values outside of the Vue render cycle, significantly improving performance by avoiding frequent re-renders source

<script setup>
const x = useMotionValue(0)
</script>

<template>
  <motion.div :style="{ x }" />
</template>

• Reduce initial bundle size from ~34kb to ~6kb by using the m component paired with LazyMotion to load features synchronously or asynchronously only when needed source

<template>
  <LazyMotion :features="domAnimation">
    <m.div :animate="{ opacity: 1 }" />
  </LazyMotion>
</template>

• Enable the strict prop on LazyMotion during development to catch accidental usage of the full motion component, which would negate the bundle size benefits of lazy loading source

• Centralize animation settings like global transitions and site-wide reducedMotion policies using MotionConfig to ensure consistent behavior across all child components source

• (experimental) Apply declarative animations directly to any standard HTML/SVG element using the v-motion directive in v2.0.0-beta.1+ without needing to wrap elements in a <motion> component source

• Ensure AnimatePresence children have unique, stable key props and are direct children of the component to correctly track their removal for exit animations source

• Synchronize layout animations across unrelated components (those that don't share a parent-child relationship but affect each other's layout) by wrapping them in a LayoutGroup source

• Prevent visual distortion of child elements during parent layout animations by applying the layout prop to the immediate children as well, enabling scale correction source

• Mark scrollable ancestors with layoutScroll and fixed-position ancestors with layoutRoot to ensure Motion correctly accounts for scroll offsets during layout measurements source