Motion for Vue

Motion for Vue (published to npm as motion-v) is the official Vue 3 port of Motion (formerly Framer Motion), bringing the same declarative <motion.div :animate="{ x: 100 }" /> API that popularized animation-as-props in React to the Vue ecosystem. It wraps motion-dom and motion-utils — the same underlying engine that powers Motion’s React and vanilla-JS builds — so Vue developers get spring physics, keyframes, gesture recognition, and shared layout animations without hand-rolling CSS transitions or reaching for a heavier animation framework.

The library is built as a Vue-idiomatic layer: components (motion, m, AnimatePresence, LazyMotion, Reorder), a v-motion directive for template-first usage, and composables like useMotionValue and useDragControls, all backed by a MotionState class that bridges Vue’s reactivity and lifecycle hooks (onMounted, onUpdated, onBeforeUnmount) to the shared animation engine. It also ships a dedicated Nuxt module entry point and a Vite/webpack resolver subpath, reflecting active investment in the two most common Vue deployment targets.

What You Get

• motion and m components for declarative, prop-driven animations (<motion.div :animate="{ x: 100 }" />)
• A v-motion directive and MotionPlugin for template-first or app-wide directive-based animation setup
• AnimatePresence and LazyMotion components for exit animations and tree-shakeable, on-demand feature loading
• Gesture support out of the box — drag, tap, and hover — via useDragControls and the underlying gesture feature set
• Layout and shared-layout animations that automatically animate size/position changes across re-renders
• A dedicated motion-v/nuxt module and Vite resolver subpath for first-class Nuxt integration

Common Use Cases

• Animating route/page transitions and modal or drawer enter/exit states with AnimatePresence
• Building drag-to-reorder lists and Kanban-style boards with the Reorder component and drag gestures
• Scroll-linked animations (progress bars, parallax, reveal-on-scroll) using the scroll value utilities
• Adding physics-based micro-interactions (buttons, cards, toggles) without writing custom CSS keyframes
• Shared/magic-move layout transitions between differently-positioned elements across view states

Under The Hood

Architecture The library is organized around a central MotionState class (in src/state) that each motion/m component instance constructs via the useMotionState composable, wiring together Vue’s injection-based context system (injectMotion, injectLayoutGroup, injectAnimatePresence, useLazyMotionContext) with Vue lifecycle hooks so the animation engine’s imperative state machine stays synchronized with Vue’s declarative render cycle. Components are generated through a createMotionComponentWithFeatures(bundle) factory (seen in src/components/motion/index.ts) that composes a domMax/domAnimation feature bundle — layout, gestures, exit-animation, and pure-animation feature sets under src/features/* — letting LazyMotion swap in a smaller feature bundle for tree-shaking. Directive support (src/directive) and the component layer are kept as parallel entry points into the same underlying state machine, so v-motion and <motion.div> are two API surfaces over one architecture rather than duplicated logic.

Tech Stack Built on Vue 3.5, TypeScript, and Vite (via rolldown-vite), with the core animation math delegated to Motion’s own framework-agnostic packages — motion-dom, motion-utils, and framer-motion/dom — reused directly rather than reimplemented, plus hey-listen for lightweight invariant/warning assertions. The package is structured as a pnpm workspace with a packages/motion (the published motion-v package), packages/plugins (a Vite/webpack resolver plugin for auto-imports), and a separate docs workspace for the documentation site, unified under one pnpm-workspace.yaml. Builds emit ESM output (dist/es), a dedicated Nuxt build target (dist/nuxt), and generated .d.ts types via vite-plugin-dts.

Code Quality The repo has a substantial unit test suite (11+ spec files) under src/**/__tests__ covering directive behavior, SVG handling, focus/arc components, and scroll offset math, run through Vitest with a --dom environment plus a separate Playwright end-to-end suite (playwright.config.ts, a test:e2e script) for browser-level animation behavior. The codebase uses TypeScript throughout with typed props (MotionProps) and exported public types, an @antfu/eslint-config-based ESLint setup, simple-git-hooks + lint-staged for pre-commit enforcement, and dedicated GitHub Actions workflows for tests, end-to-end runs, and releases, indicating a maintained, CI-gated contribution workflow rather than an unverified side project.

API Design The API deliberately mirrors Framer Motion’s React API (same prop names — animate, initial, exit, variants — just bound with : instead of JSX spread), which minimizes the learning curve for any team that has used Motion/Framer Motion before and lets the project’s extensive React-side documentation transfer conceptually. Vue-specific ergonomics are layered on top rather than bolted awkwardly: a directive form (v-motion) for teams that prefer template-driven markup, a plugin (MotionPlugin) for global setup, and composables for imperative control (useMotionValue, useDragControls) — giving three levels of API surface (declarative component, directive, composable) for different comfort levels with minimal required boilerplate to animate a first element.