motiondivision/motion-vue
motion-v
Version:
2.0.1 (Mar 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.1 (Mar 2026)
References:
Docs
— API reference, guides
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
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
Use
LazyMotion
+
m
component instead of
motion
to reduce the initial bundle from ~34kb to ~6kb — load
domAnimation
(+18kb) for variants/exit/gestures or
domMax
(+28kb) when you also need drag and layout animations. Add
:strict="true"
to catch accidental
motion
imports inside
LazyMotion
at dev time
source
Render live motion value output with
rather than syncing to Vue state —
RowValue
writes to
innerHTML
directly and bypasses Vue's reactivity cycle, keeping fast-changing values off the render path
source
Set
reducedMotion="user"
on
MotionConfig
at the app root — the default is
"never"
, meaning transform and layout animations run regardless of the OS accessibility setting unless you explicitly opt in
source
For layout animations, apply changing CSS to
:style
(not
:animate
) and let the
layout
prop handle the transition — if the value is placed in
:animate
, Motion's FLIP measurement will conflict with it
source
Set
borderRadius
and
boxShadow
via
:style
(not CSS classes) on
layout
-animated elements — Motion auto-corrects scale distortion on these properties only when they are set as inline style motion values
source
Add
layoutScroll
to scrollable container ancestors and
layoutRoot
to fixed-position ancestors of layout-animated elements — without these props, Motion measures child positions incorrectly when scroll offset or viewport offset is non-zero
source
Never place
v-if
on
AnimatePresence
itself — if it unmounts, it cannot intercept the exit of its children. The conditional must be on the direct child:
source
Use dynamic variants with the
custom
prop for per-element stagger rather than computing delay in reactive Vue state — pass
:custom="index"
to each
motion
component and resolve the delay inside the variant function, keeping stagger logic declarative and allocation-free
source
Prefer
useMotionValue
over CSS variable animation for values used across many children — animating a CSS variable always triggers paint on every frame, while a
MotionValue
passed to
:style
runs through Motion's optimised DOM renderer without touching the Vue render cycle
source
Use the
v-motion
directive (new in v2.0.0-beta.1) to add animation to any native HTML or SVG element without a wrapper
component — register globally via
app.use(MotionPlugin)
or per-component via
createMotionDirective
. Register reusable animation presets via the
presets
option to create project-wide shorthand directives like
v-fade-in
source