Motion Blocks

Docs

Installation

Install animated Web Components into your project with the Motion Blocks CLI. Motion Blocks uses motion-blocks.json only.

Quick Start

Initialize Motion Blocks in your project, then add any component by name: 

pnpm dlx motion-blocks init
pnpm dlx motion-blocks add magnetic

The CLI will automatically:

  • Write motion-blocks.json with framework-aware paths
  • Download component source files from the registry
  • Resolve registry dependencies (e.g. shared gsap helper)
  • Install required npm dependencies (GSAP, Lit, etc.)
  • Enable experimentalDecorators in your tsconfig when needed
  • Print a framework-specific usage snippet after install

Each component page shows the exact motion-blocks add command ready to copy.

CLI Commands

Browse and inspect the registry before installing:

pnpm dlx motion-blocks list

Use --all to include hidden helper libs such as the shared gsap module: 

pnpm dlx motion-blocks list --all

Inspect detected project info and your config:

pnpm dlx motion-blocks info

Maintainers can validate registry source manifests without writing files: 

pnpm registry:build:check

Configuration

motion-blocks init writes a motion-blocks.json file at your project root. You can edit it to override detection results: 

1{2  "$schema": "https://motionkit.org/schemas/motion-blocks.json",3  "registry": "https://motionkit.org/r",4  "framework": "astro",5  "packageManager": "pnpm",6  "componentsDir": "src/components/motion-blocks",7  "helpersDir": "src/lib/motion-blocks"8}

Key fields:

  • registry — base URL for registry payloads (required)
  • framework — affects install paths and usage snippets
  • componentsDir — where component files are written
  • helpersDir — where shared helper libs are written

Lit-based components need decorators enabled when your project compiles TypeScript: 

1{2  "compilerOptions": {3    "experimentalDecorators": true4  }5}

Project Structure

After installing components, your project typically looks like this: 

src/├── components/│   └── motion-blocks/          # Motion Blocks components│       ├── magnetic/│       │   └── magnetic-element.ts│       ├── card-stack/│       │   └── card-stack-element.ts│       └── ...├── lib/│   └── motion-blocks/           # Shared helpers (e.g. gsap)└── pages/

Register custom elements in client code before using them in markup: 

1import "./magnetic-element";2 3// The component registers itself automatically.4// Use it in your HTML:5<motion-magnetic></motion-magnetic>

Framework Support

Motion Blocks components work with any framework that supports Web Components. Starter templates live in the repo under templates/:

Astro
Astro First-class support
Next.js
Next.js Client components
SvelteKit Full support
Vue Web Components
React Custom Elements
JavaScript
Vanilla JS Any setup

Troubleshooting

No motion-blocks.json found

Run motion-blocks init in your project root before motion-blocks add.

Registry item not found

Run motion-blocks list to see available names. Check that registry in motion-blocks.json points at a valid catalog URL.

Invalid registry item

The fetched payload failed validation. If you maintain the registry, run motion-blocks build --check from the Motion Kit repo to inspect source manifests.

Unsafe target path

The CLI refused to write outside your project. This indicates a bad target path in the registry item — report it upstream.

File already exists

Re-run with --overwrite to replace installed files, or delete the conflicting file manually.

Dependency install failed

Retry with --no-install and run the printed package manager command manually. pnpm store mismatches can be fixed with rm -rf node_modules && pnpm install.

Asset copy failed

Check your network connection and the registry URL. Assets are fetched from the registry, not inlined in payloads.

Unsupported framework

If motion-blocks init cannot detect your framework, set framework manually in motion-blocks.json and adjust componentsDir / helpersDir to match your project layout.

Components not rendering?

Register the custom element in client code before using it in markup. In Astro, import in a <script> block, not frontmatter.

Build errors?

Ensure your build tool supports TypeScript, Web Components, and Lit decorators. Enable experimentalDecorators in tsconfig.json when you compile registry source.