Introduction

Motion Blocks is a collection of production-ready animated components built as Custom Elements and distributed through a flat-file registry. Each component ships as source code dropped directly into your project — no package manager dependency, no abstraction layer between you and the animation.

It is built around a small set of ideas: open code you own and control, a consistent Web Component interface that works across frameworks, and a distribution model that keeps installation as simple as one command.

This is not a library you install from npm and import. It is a registry you pull from. When you add a Motion Blocks component, the source files are copied into your project and become part of your codebase. You own them.

Traditional animation libraries ask you to accept their runtime, wrap their components, and fight their APIs whenever your design deviates from their defaults. Motion Blocks sidesteps that entirely — if you want to change an easing curve or adjust a timing value, you open the file and change it.

Every component is a Custom Element — framework-agnostic by design. Built with Lit or vanilla HTMLElement, they work in Astro, Next.js, SvelteKit, or plain HTML without modification.

Each component shares a consistent interface: shadow DOM for style isolation, GSAP for animation, and a replay() method that re-triggers the animation on demand. There is nothing to learn beyond the HTML attribute API each component publishes — and those are all documented in the API Reference on each component page.

Motion Blocks uses a flat-file registry schema: each component defines its files, dependencies, and installation targets. The motion-blocks CLI reads motion-blocks.json in your project and places source files exactly where they belong. It does not read shadcn components.json.

Initialize and install with two commands:

pnpm dlx motion-blocks init

pnpm dlx motion-blocks add magnetic

Each component's page has the exact motion-blocks add command ready to copy. Re-run it at any time to pull in an updated version.

You receive the full component source — TypeScript, GSAP setup, shadow DOM styles and all. There is no compiled black box to debug. Every animation curve, every timing value, every DOM decision is yours to read and change.

This also makes Motion Blocks components straightforward for LLMs to work with. The source is small, self-contained, and follows a consistent pattern — making it easy to ask an AI to extend, restyle, or compose components without fighting an opaque API.