motiondivision/motion
github.com/motiondivision/motion ↗ · 1825 files · 6.1 MB
Motion An open source animation library for JavaScript, React and Vue bash React / JavaScript npm install motion Vue npm install motion-v Table of Contents 1.
Overview
Motion is a TypeScript animation library for JavaScript and React developers, distributed through the public motion package and implemented across framer-motion, motion-dom, and motion-utils. It combines imperative animation, React components and hooks, gestures, scroll-linked effects, layout projection, browser view transitions, and optional GPU-object adapters. Its distinctive architecture shares motion values and rendering infrastructure between declarative React usage and imperative DOM animation, choosing browser-native animation or JavaScript execution according to capabilities and options. This brief describes inspected source at commit f5838ce47b323ce2713cb2effc5afaa5b6120a44; it is a bounded investigation, not an exhaustive audit.
System map
The repository ships animation packages rather than a hosted application backend. Public entrypoints delegate to implementations spread across React orchestration, a shared DOM engine, and foundational utilities. Development applications provide browser fixtures for HTML, React, React 19, and Next.js. Runtime state is held in motion values, effect caches, component refs, and projection trees; release tooling separately writes artifacts and contacts external systems.
- The dependency chain is motion → framer-motion → motion-dom → motion-utils, with exact internal version 14.0.0 in the inspected manifests.
- The default motion entrypoint re-exports framer-motion/dom; motion/react exposes explicit motion and m bindings alongside the React package's wildcard exports.
- The public package exports JavaScript, mini, debug, three, vgpu, React, React-client, React-m, React-mini, and React-view-transition subpaths with declaration, CommonJS, and ESM targets.
- AsyncMotionValueAnimation selects NativeAnimationExtended only for animatable, non-handoff, browser-supported options; native construction exceptions fall back to JSAnimation.
- Development boundaries are Vite React on TEST_PORT or 9990, Vite React 19 on TEST_PORT or 9991, HTML Vite on 8000, and a private Next.js 15.5.24 fixture application.
- Yarn 3.6.4 workspaces are orchestrated by Turbo; build dependencies run upstream first, and packages compile TypeScript before Rollup emits distributable bundles.
- Inspected animation state is process-local: createEffect uses a WeakMap per subject, MotionValueState owns keyed bindings, and React VisualElements live in refs rather than a persistent storage service.
- Distribution and integration tooling includes Lerna publication, postpublish tag pushing, changelog copying into another checkout, and a bearer-authenticated Slack-update API call.
Feature catalog
The user-facing surface is primarily importable APIs consumed by application developers. React offers animated HTML and SVG components, interaction props, lazy feature loading, and motion-value hooks. Imperative APIs target values, selectors, objects, sequences, layout changes, and browser view-transition layers. Optional adapters extend the same animation machinery to Three.js and vgpu subjects.
- motion components support HTML or SVG rendering and activate animation, exit, drag, focus, hover, tap, pan, viewport, and layout features according to their props.
- animate accepts scalar values, MotionValues, elements/selectors, objects, and sequences; animateMini exposes a scoped element-animation API returning grouped playback controls.
- Sequence animation supports callback segments by replacing callbacks with subscribed MotionValues, compiling sequence definitions, and animating each resulting subject.
- The React API exports useMotionValue, useMotionTemplate, useScroll, useFollowValue, useSpring, useTransform, useVelocity, and useAnimate; MotionConfig exposes default transitions, reducedMotion, skipAnimations, nonce, and prop validation.
- scroll can deliver progress callbacks or attach playback controls to scroll progress, with axis, source/container, target, and offset-dependent behavior; inView is also exported from the DOM entrypoint.
- AnimatePresence retains removed keyed children until exit completion and supports sync or wait sequencing; LazyMotion enables synchronous or asynchronous feature bundles for lightweight m components.
- Layout APIs use layout/layoutId props or data-layout/data-layout-id attributes; view-transition builders support paired subjects, crop overrides, and nested-layer grouping, while unsupported startViewTransition still executes the DOM update.
- threeEffect binds transforms, materials, and uniforms using preRender writes; vgpuEffect supports scene and shader-related subjects and batches changed values into one set operation per subject per frame.
Data flow
Inputs enter through component props, imperative subjects and keyframes, selectors, or browser events. Subject resolution and option normalization feed motion values, keyframe resolvers, and animation playback objects. Rendering is scheduled through ordered frame phases or delegated to browser animation APIs. Completion and cleanup update group controls, effect bindings, and retained React children; the separately inspected release path writes changelog artifacts.
- Selector input is resolved against scope.current when scoped, otherwise document; null subjects resolve empty, NodeLists become arrays, and arrays discard null members before dispatch.
- animateSubject clones transitions per subject, evaluates functional delay with index and total, routes DOM elements through animateElement, and routes other objects through a matching registered effect or propEffect.
- animateElement shares an existing VisualElement's values when supplied; otherwise it selects HTML-style or SVG effects and provides an EffectSubject adapter for DOM reads, rendering, and measurement.
- animateEffectSubject reuses bound values or creates MotionValues; non-DOM origins come from an explicit first keyframe or effect.read(), and unreadable origins trigger an invariant.
- animateMotionValue combines value-specific options with velocity and callbacks, translates public seconds to milliseconds, and applies skip-animation conditions before choosing synchronous JS or asynchronous resolution.
- DOMKeyframesResolver samples CSS variables and detects positional unit changes; queued resolvers batch origin/end measurement and temporary transform removal before reporting resolved keyframes.
- MotionValue updates notify change subscribers and dependents; MotionValueState deduplicates scheduled writes, and style effects emit transforms, transform origins, CSS custom properties, or typed style values.
- The changelog data path reads CHANGELOG.md, serializes escaped version/date/content/type/slug CSV rows into changelog.csv, then optionally copies that file to motion-api's site content as motion.csv.
Behavior traces
Three principal flows were followed across concrete source files: playground startup, imperative DOM animation, and scroll-driven playback. Additional traces cover React component mounting, scoped cleanup, exit completion, and browser view transitions. These traces describe execution order and material branches observed in source. They do not report runtime verification.
- Playground startup: main.tsx calls createRoot(...).render(<StrictMode><App/></StrictMode>); App eagerly imports fixture App exports, reads example/test query parameters, prioritizes example, and renders the selected module or ExampleList.
- Primary animation entry: motion → framer-motion/dom → createScopedAnimate's scopedAnimate → animateSubject → resolveSubjects; sequence-shaped input instead enters animateSequence before subject dispatch.
- DOM animation continuation: animateSubject → animateElement → animateValues or animateEffectSubject → value.start(animateMotionValue(...)) → AsyncMotionValueAnimation → keyframe resolution → native animation or JSAnimation; NativeAnimation construction failures take the JS branch.
- Scroll playback: scroll defaults axis/container and calls attachToAnimation; compatible native ranges attach a cached ScrollTimeline/ViewTimeline, while fallback observe pauses controls and sets time to iterationDuration × measured axis progress.
- Scroll measurement and disposal: scrollInfo creates handlers and one listener per container; scroll events schedule measureAll in frame.read, then notifyAll in preUpdate; final subscriber removal releases scroll/resize listeners and content-size polling.
- React mount: motion proxy property access creates/caches a component; createMotionComponent initializes visual state and browser-only VisualElements; layout effects update features and schedule rendering, and animateChanges normally runs in a passive effect but runs earlier for optimized-appear handoff.
- Scoped and presence completion: useAnimate registers groups in scope.animations and stops remaining groups on unmount; AnimatePresence marks individual exits complete, waits for all tracked exits, re-diffs children, and invokes safeToRemove/onExitComplete.
- View transition: startViewAnimation names/measures old layers and commits CSS, calls document.startViewTransition(callback), awaits update(), resolves/measures new layers and crop rules, wraps generated animations, and removes names/CSS on completion; unsupported browsers execute update without animation.
Testing signals
Tests and CI were inspected, not executed; no passing result, coverage percentage, or runtime performance result is asserted. The repository combines co-located Jest tests, React browser tests in Cypress, and Playwright browser suites. Inspected tests exercise registry precedence, presence initialization, playback controls, scroll parity, and React view transitions. Inspection was bounded, and browser support checks, project selection, and CI wiring limit what test existence establishes.
- Jest uses ts-jest and co-located __tests__ patterns; framer-motion separates JSDOM client tests from Node SSR tests, with JUnit output configured for both.
- Effect-registry unit tests assert registration lookup, newest-effect precedence, removal, deduplication, and animation from a readable initial value.
- AnimatePresence tests use React rendering helpers and frame callbacks to check default initial animation, initial={false} suppression, and ordinary rerenders.
- Cypress has separate React 18/19 base URLs and JUnit files; the inspected scroll-accelerate spec checks direct acceleration propagation, non-compositor propagation, and exclusion of chained useTransform.
- Playwright defines Chromium and WebKit HTML projects plus a Chromium React 19 project; CI forbids focused tests, retries twice, uses one worker, and captures traces on first retry. This configuration contains no Firefox project.
- Inspected Playwright tests cover playback/repeat/interruption, compare native and JS scroll progress within 0.01 across positions and resizes, and inspect React view-transition pseudo-animation timing; the latter skips when startViewTransition is unsupported.
- CircleCI builds after an immutable install, then runs Jest, size budgets, React 18, React 19, HTML, and Next.js jobs; its inspected workflow does not schedule the Makefile's test-e2e target that additionally runs Playwright.
- Validation limits are explicit: documentation warns JSDOM lacks WAAPI and real layout, browser tests can skip unsupported APIs, and the inspected CI job list establishes configured execution paths rather than actual run outcomes.
Risk map
The observations below identify sensitive boundaries and change hotspots, not confirmed vulnerabilities. Release scripts have filesystem and network effects outside the animation runtime. Animation correctness depends on browser capability detection, shared rendering ownership, lifecycle ordering, and bundle/context identity. Two retention and CSP concerns are explicitly labeled hypotheses requiring targeted verification.
- Release commands have substantial side effects: new invokes Lerna publication and site mirroring, postpublish pushes tags, and Makefile clean removes node_modules and invokes git clean -fdX.
- pushToSite copies a file outside this checkout into an environment-selected MOTION_API_PATH or ~/Sites/motion-api; it checks destination existence but the source does not constrain the destination to this repository.
- notifySlack loads dotenv, accepts an overridable SLACK_UPDATE_API_URL, and sends UPDATE_SECRET_TOKEN as a bearer header; production requires a token, while development permits a test token and local HTTP.
- The Claude workflow executes on @claude-bearing issue/comment/review content, requests id-token write permission, and delegates to a version-tagged third-party action using an OAuth-secret reference; authorization beyond the visible condition is outside this source inspection.
- Hypothesis: the module-level timelineCache can retain detached containers and targets because it uses nested Maps with no eviction in get-timeline.ts; listener cleanup in attachToAnimation does not remove those cache entries. (inferred)
- Hypothesis: strict CSP may block view-transition CSS because css.commit creates and appends a style element without assigning a nonce, despite MotionConfig exposing a nonce option. Browser verification is needed to establish impact. (inferred)
- Bundling and public export shape are compatibility hotspots: shared CommonJS contexts are required for LazyMotion/m communication, and motion/react deliberately avoids a duplicate-source re-export pattern documented as causing Turbopack OOM.
- Projection and keyframe measurement change live DOM state: projection cancels optimized transforms before snapshots, resets transforms before measuring nodes, and keyframe resolution temporarily renders styles and restores scroll position. Frame-order changes therefore cross multiple rendering responsibilities.
Extension points
Extension mechanisms exist at subject dispatch, renderer construction, feature loading, and animation scheduling boundaries. The effect API is the clearest public adapter mechanism and already supports GPU integrations. React features are enabled through a shared definition table and supplied as bundles. Development fixture discovery and package export maps provide separate extension surfaces for tests and distribution.
- animate.addEffect/removeEffect expose a subject registry; registration requires test() and read(), removes duplicate registration, and puts the newest effect first in dispatch order.
- createEffect accepts an addValue callback plus optional test/read/step options and returns a callable binding API with get(), flush(), state(), and per-call cleanup.
- threeEffect and vgpuEffect demonstrate adapters that claim subjects, read initial values, and schedule writes in frame.preRender; their implementations are exposed through dedicated motion subpaths.
- React feature extension uses featureProps to derive isEnabled checks; loadFeatures merges supplied feature packages into the existing shared table and writes it back through setFeatureDefinitions.
- createMotionComponent accepts preloaded features, a CreateVisualElement factory, forwardMotionProps, and explicit HTML/SVG type; createDomVisualElement selects HTMLVisualElement or SVGVisualElement.
- LazyMotion supports a direct feature bundle or a promise-returning loader, separates renderer from loaded features, and publishes the renderer and strict flag through LazyContext.
- createProjectionNode injects resize-listener, parent, scroll-measurement, scroll-root, and transform-reset behavior; AsyncMotionValueAnimation separately accepts an element-specific KeyframeResolver.
- New React fixtures plug into eager import.meta.glob discovery by exporting App; React 19 reuses React fixture files, while new public package APIs also require the appropriate export-map targets.
Contributor handoff
Begin with the actual public entrypoint and follow ownership into the implementation package before editing. The inspected tests and CI were not executed, and the inventory is bounded rather than exhaustive coverage. Preserve package compatibility, shared state ownership, frame timing, and browser fallback branches. Future execution should use repository-defined checks only when authorized, with release and external-write commands treated separately.
- Read AGENTS.md, the affected manifests, and actual re-export files first: the short architecture description calls motion a re-export package, but its default entrypoint specifically targets framer-motion/dom.
- Preserve exact internal package versions and Yarn 3.6.4; internal-dependencies.test.ts checks every workspace dependency category against public package versions and verifies Lerna's exact-version setting.
- Follow library conventions: interface type definitions, named exports, const/let, and strict equality are ESLint rules; shared TypeScript settings enable strict null checks, noImplicitAny, and unused-symbol checks.
- Use time.now() for frame-synchronized timestamps; its cached value comes from frameData during frame processing or manual timing and is cleared by a microtask.
- For animation changes, inspect subject dispatch, animateElement, and effect-state handoff together; existing VisualElement ownership and handOffElementState prevent independent renderers from driving the same values.
- When execution is authorized, choose package Jest client/server tests for logic and SSR, Cypress for React/browser behavior, and yarn test-playwright for browser suites; tests and CI were inspected here, not executed, so these commands are candidate checks rather than passing evidence.
- Keep React 18/19 fixture compatibility and browser-specific checks explicit: React 19 shares fixture sources but deduplicates/aliases React locally, and JSDOM cannot establish WAAPI or real-layout correctness.
- Before public-API or bundling changes, inspect Rollup context sharing and bundle budgets; before any operational command, inspect scripts because publication, tag pushes, changelog mirroring, and notifications carry external effects.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 1233 | 97% |
| HTML | 307 | docs/config |
| Markdown | 170 | docs/config |
| JSON | 52 | docs/config |
| JavaScript | 40 | 3% |
| CSS | 6 | docs/config |
| YAML | 4 | docs/config |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (900 files)
Source layout — packages/
| Path | Files |
|---|---|
packages/config/ | 2 |
packages/motion/ | 30 |
packages/motion-dom/ | 66 |
packages/motion-utils/ | 57 |
Repository structure
| Top-level path | Files |
|---|---|
packages/ | 900 |
dev/ | 731 |
plans/ | 144 |
tests/ | 16 |
.agents/ | 5 |
.github/ | 4 |
scripts/ | 3 |
.devcontainer/ | 2 |
Docs found: AGENTS.mdCLAUDE.mdCONTRIBUTING.mdLICENSE.mdREADME.md
Package
package.json — motion-one v0.0.0, 55 declared dependencies.
@cypress/webpack-preprocessor@gsap/react@playwright/test@rollup/plugin-alias@rollup/plugin-node-resolve@rollup/plugin-replace@rollup/plugin-terser@testing-library/dom@testing-library/jest-dom@testing-library/react@types/jest@types/node
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructionsCLAUDE.md— Claude instructions.github/workflows/claude.yml— GitHub Actions workflowdev/react-19/vite.config.ts— Vite configdev/react-19/src/App.tsx— React rootdev/react-19/src/main.tsx— Vite React entrypointdev/html/vite.config.js— Vite configdev/react/vite.config.ts— Vite configdev/react/src/App.tsx— React root
Structural health signals
Average score 8.5/10 across 96 analyzed source files; 5 hotspots surfaced.
packages/motion-dom/src/animation/generators/spring.ts— 535 lines, score 6.2 (Large file, Deep nesting)packages/motion-dom/src/render/VisualElement.ts— 939 lines, score 6.2 (Large file, Deep nesting)packages/framer-motion/cypress/integration/layout-shared.ts— 1206 lines, score 6.2 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
f5838ce47b322026-10-02 — v14.0.0351f7d0c027f2026-10-02 — Updating changelog5da7dcd8b7222026-10-02 — Merge pull request #3889 from motiondivision/cursor/v14-remove-shims-4e790897128336762026-10-02 — Remove 13.5.1 compatibility shims for framer-motion 13.0–13.4d4638ea17bcd2026-10-02 — v13.5.1