Motion Primitives

Motion-Primitives

Motion-primitives is a copy-in-source animation component library (same philosophy as shadcn/ui) built on Motion for React (motion, the successor to framer-motion) and Tailwind. 33 components across six categories: core containers, text effects, number effects, interactive elements, toolbars, and advanced effects. MIT licensed, by @ibelick.

Why it's good: it occupies the layer shadcn deliberately doesn't — the expressive/delight layer. shadcn gives you accessible structure; motion-primitives gives you the animated moments (a headline that reveals, a KPI that rolls, a thumbnail that morphs into a fullscreen preview). Because components are copied into your repo, they're editable and there's no runtime dependency beyond motion itself — no version treadmill, no lock-in.

Setup (once per project)

Prerequisites: Tailwind, then:

npm install motion lucide-react
# lib/utils.ts must exist with the cn() helper (clsx + tailwind-merge)

Add components one at a time — either CLI works, both copy source into components/motion-primitives/ (path configurable):

npx motion-primitives@latest add text-effect
# or via shadcn CLI:
npx shadcn@latest add "https://motion-primitives.com/c/text-effect.json"

If CLI/network is unavailable, copy the component file directly from github.com/ibelick/motion-primitives → components/core/<name>.tsx. Imports use motion/react (not framer-motion).

Per-component dependencies (verified by compile): the CLI resolves these automatically, but manual copies must add them: infinite-slider and sliding-number need react-use-measure; morphing-dialog needs lucide-react and the repo's hooks/useClickOutside.tsx (copy it to hooks/). If a copied component fails to resolve an import, check the repo's hooks/ directory before assuming it's an npm package.

Workflow

1. Decide whether motion belongs here at all (see "Where it makes sense" below). If the surface is a dense work queue, the answer is usually no.
2. Pick the component from the decision table below.
3. Read references/component-api.md for that component's exact props — never write props from memory. Several props are non-obvious (e.g. Tilt's reverse prop is spelled isRevese in the shipped source; most text components accept children: string only, not ReactNode).
4. Read references/recipes.md if the task matches a recipe (hero reveal, KPI ticker, asset-morph preview, marquee, streaming-text shimmer).
5. Compose, don't stack. One motion idea per screen region. Two animated text effects next to each other read as broken, not polished.

Where it makes sense

The test: motion should either explain a state change (this thing appeared / moved / completed) or reward a moment that matters (first load, launch, success). Motion that does neither is noise.

Decision table — task → component

Note on toolbars: toolbar-dynamic and toolbar-expandable are page-level demos (default exports, hard-coded content), not composable primitives. Treat them as reference implementations to adapt, not components to install and use as-is.

Non-negotiables

• Every motion-primitives component is a client component — it or its parent needs 'use client'. Keep the boundary at the leaf: animate the headline component, not the whole page.
• Import from motion/react, never framer-motion, in any code you write alongside these components.
• Text-effect family takes children: string. Passing JSX will type-error — wrap mixed content by composing multiple instances instead.
• Don't animate layout-critical dimensions on containers with data-heavy children; animate transform/opacity instead (the components already do this internally — keep your customizations consistent with it).
• Check references/component-api.md before writing props. If a prop you want isn't listed, it doesn't exist — extend the copied source instead of guessing.