# Framer Motion (Motion v12) — Full Reference > Framer Motion was renamed to **Motion** in mid-2025. The npm package is now `motion`, > the import path is `motion/react`. All APIs are identical. `framer-motion` still works. ## Table of Contents 1. [Package & Import Paths](#package--import-paths) 2. [Two Types of Scroll Animation](#two-types-of-scroll-animation) 3. [useScroll — Options Reference](#usescroll--options-reference) 4. [useTransform — Full Reference](#usetransform--full-reference) 5. [useSpring for Smoothing](#usespring-for-smoothing) 6. [Recipes with Copilot Prompts](#recipes-with-copilot-prompts) - Scroll progress bar - Reusable ScrollReveal wrapper - Parallax layers - Horizontal scroll section - Image reveal with clipPath - Scroll-linked navbar (hide/show) - Staggered card grid - 3D tilt on scroll 7. [Variants Pattern for Stagger](#variants-pattern-for-stagger) 8. [Motion Value Events](#motion-value-events) 9. [Next.js & App Router Notes](#nextjs--app-router-notes) 10. [Accessibility](#accessibility) 11. [Common Copilot Pitfalls](#common-copilot-pitfalls) --- ## Package & Import Paths ```bash npm install motion # recommended (renamed 2025) npm install framer-motion # still works — same API ``` ```js // Recommended (Motion v12+) import { motion, useScroll, useTransform, useSpring, useMotionValueEvent } from 'motion/react'; // Legacy — still valid import { motion, useScroll, useTransform } from 'framer-motion'; ``` **Motion v12 new features (2025):** - Hardware-accelerated scroll via browser ScrollTimeline API - `useScroll` and `scroll()` now GPU-accelerated by default - New color types: `oklch`, `oklab`, `color-mix` animatable directly - Full React 19 + concurrent rendering support --- ## Two Types of Scroll Animation ### Scroll-triggered (fires once when element enters viewport) ```jsx Content ``` `viewport.margin` — negative value triggers animation before element fully enters view. `viewport.once` — `true` means animate once, never reverse. ### Scroll-linked (continuous, tied to scroll position) ```jsx const { scrollYProgress } = useScroll(); const opacity = useTransform(scrollYProgress, [0, 1], [0, 1]); return Content; ``` The value updates on every scroll frame — must use `style` prop, not `animate`. --- ## useScroll — Options Reference ```js const { scrollX, // Absolute horizontal scroll (pixels) scrollY, // Absolute vertical scroll (pixels) scrollXProgress, // Horizontal progress 0→1 between offsets scrollYProgress, // Vertical progress 0→1 between offsets } = useScroll({ // Track a scrollable element instead of the viewport container: containerRef, // Track an element's position within the container target: targetRef, // Define when tracking starts and ends // Format: ["target position container position", "target position container position"] offset: ['start end', 'end start'], // Common offset pairs: // ['start end', 'end start'] = track while element is anywhere in view // ['start end', 'end end'] = track from element entering to bottom of page // ['start start', 'end start'] = track while element exits top // ['center center', 'end start']= track from center-center to exit // Update when content size changes (small perf cost, false by default) trackContentSize: false, }); ``` **Offset string values:** - `start` = `0` = top/left edge - `center` = `0.5` = middle - `end` = `1` = bottom/right edge - Numbers 0–1 also work: `[0, 1]` = `['start', 'end']` --- ## useTransform — Full Reference ```js // Map a motion value from one range to another const y = useTransform(scrollYProgress, [0, 1], [0, -200]); // Multi-stop interpolation const opacity = useTransform( scrollYProgress, [0, 0.2, 0.8, 1], [0, 1, 1, 0] ); // Non-numeric values (colors, strings) const color = useTransform( scrollYProgress, [0, 0.5, 1], ['#6366f1', '#ec4899', '#f97316'] ); // CSS string values const clipPath = useTransform( scrollYProgress, [0, 1], ['inset(0% 100% 0% 0%)', 'inset(0% 0% 0% 0%)'] ); // Disable clamping (allow values outside output range) const y = useTransform(scrollYProgress, [0, 1], [0, -200], { clamp: false }); // Transform from multiple inputs const combined = useTransform( [scrollX, scrollY], ([x, y]) => Math.sqrt(x * x + y * y) ); ``` **Rule:** `useTransform` output is a `MotionValue`. It must go into the `style` prop of a `motion.*` element. Plain `
` will NOT work — must be ``. --- ## useSpring for Smoothing Wrap any MotionValue in `useSpring` to add spring physics — great for progress bars that feel alive. ```js const { scrollYProgress } = useScroll(); const smooth = useSpring(scrollYProgress, { stiffness: 100, // Higher = faster/snappier response damping: 30, // Higher = less bounce restDelta: 0.001 // Precision threshold for stopping }); return ; ``` For a subtle lag (not physics), use `useTransform` with `clamp: false` and an eased range instead. --- ## Recipes with Copilot Prompts ### 1. Scroll Progress Bar **Copilot Chat Prompt:** ``` Framer Motion: fixed scroll progress bar at top of page. useScroll for page scroll progress, useSpring to smooth scaleX. stiffness 100, damping 30. Grows left to right. ``` ```tsx 'use client'; import { useScroll, useSpring, motion } from 'motion/react'; export function ScrollProgressBar() { const { scrollYProgress } = useScroll(); const scaleX = useSpring(scrollYProgress, { stiffness: 100, damping: 30, restDelta: 0.001, }); return ( ); } ``` --- ### 2. Reusable ScrollReveal Wrapper **Copilot Chat Prompt:** ``` Framer Motion: reusable ScrollReveal component that wraps children with fade-in-up entrance animation using whileInView. Props: delay (default 0), duration (default 0.6), once (default true). viewport margin -80px. TypeScript. 'use client'. ``` ```tsx 'use client'; import { motion } from 'motion/react'; interface ScrollRevealProps { children: React.ReactNode; delay?: number; duration?: number; once?: boolean; className?: string; } export function ScrollReveal({ children, delay = 0, duration = 0.6, once = true, className }: ScrollRevealProps) { return ( {children} ); } // Usage: //

Section Title

 ``` --- ### 3. Parallax Layers **Copilot Chat Prompt:** ``` Framer Motion parallax section: background moves y from 0% to 30% (slow), foreground text moves y from 50 to -50px (fast). Both use target ref with offset ['start end', 'end start']. Fade out at top and bottom using opacity useTransform [0, 0.3, 0.7, 1] → [0,1,1,0]. ``` ```tsx 'use client'; import { useRef } from 'react'; import { motion, useScroll, useTransform } from 'motion/react'; export function ParallaxSection() { const ref = useRef(null); const { scrollYProgress } = useScroll({ target: ref, offset: ['start end', 'end start'], }); const backgroundY = useTransform(scrollYProgress, [0, 1], ['0%', '30%']); const textY = useTransform(scrollYProgress, [0, 1], [50, -50]); const opacity = useTransform(scrollYProgress, [0, 0.3, 0.7, 1], [0, 1, 1, 0]); return (

Parallax Title

Scrolls at a different speed
); } ``` --- ### 4. Horizontal Scroll Section **Copilot Chat Prompt:** ``` Framer Motion horizontal scroll: 4 cards scroll horizontally as user scrolls vertically. Outer container ref height 300vh controls speed (sticky pattern). useScroll tracks outer container, useTransform maps scrollYProgress to x '0%' → '-75%'. ``` ```tsx 'use client'; import { useRef } from 'react'; import { motion, useScroll, useTransform } from 'motion/react'; const cards = [ { id: 1, title: 'Card One', color: 'bg-indigo-500' }, { id: 2, title: 'Card Two', color: 'bg-pink-500' }, { id: 3, title: 'Card Three', color: 'bg-amber-500' }, { id: 4, title: 'Card Four', color: 'bg-teal-500' }, ]; export function HorizontalScroll() { const containerRef = useRef(null); const { scrollYProgress } = useScroll({ target: containerRef, offset: ['start start', 'end end'], }); const x = useTransform(scrollYProgress, [0, 1], ['0%', '-75%']); return (
{cards.map(card => (

{card.title}

))}
); } ``` --- ### 5. Image Reveal with clipPath **Copilot Chat Prompt:** ``` Framer Motion: image reveals left to right as it scrolls into view. useScroll target ref, offset ['start end', 'center center']. useTransform clipPath from 'inset(0% 100% 0% 0%)' to 'inset(0% 0% 0% 0%)'. Also scale from 1.15 to 1. ``` ```tsx 'use client'; import { useRef } from 'react'; import { motion, useScroll, useTransform } from 'motion/react'; export function ImageReveal({ src, alt }: { src: string; alt: string }) { const ref = useRef(null); const { scrollYProgress } = useScroll({ target: ref, offset: ['start end', 'center center'], }); const clipPath = useTransform( scrollYProgress, [0, 1], ['inset(0% 100% 0% 0%)', 'inset(0% 0% 0% 0%)'] ); const scale = useTransform(scrollYProgress, [0, 1], [1.15, 1]); return (
); } ``` --- ### 6. Scroll-linked Navbar (Hide on Scroll Down) **Copilot Chat Prompt:** ``` Framer Motion navbar: transparent when at top, white with shadow after 80px. Hide by sliding up when scrolling down, reveal when scrolling up. Use useScroll, useMotionValueEvent to detect direction. Animate y, backgroundColor, boxShadow with motion.nav. ``` ```tsx 'use client'; import { useRef, useState } from 'react'; import { motion, useScroll, useMotionValueEvent } from 'motion/react'; export function Navbar() { const { scrollY } = useScroll(); const [scrolled, setScrolled] = useState(false); const [hidden, setHidden] = useState(false); const prevRef = useRef(0); useMotionValueEvent(scrollY, 'change', latest => { const nextScrolled = latest > 80; const nextHidden = latest > prevRef.current && latest > 200; setScrolled(current => (current === nextScrolled ? current : nextScrolled)); setHidden(current => (current === nextHidden ? current : nextHidden)); prevRef.current = latest; }); return ( ); } ``` --- ### 7. Staggered Card Grid **Copilot Chat Prompt:** ``` Framer Motion: card grid with stagger entrance. Use variants: container has staggerChildren 0.1, delayChildren 0.2. Each card: hidden (opacity 0, y 40, scale 0.96) → visible (opacity 1, y 0, scale 1). Trigger with whileInView on the container. Once. ``` ```tsx 'use client'; import { motion } from 'motion/react'; const containerVariants = { hidden: {}, visible: { transition: { staggerChildren: 0.1, delayChildren: 0.2 } } }; const cardVariants = { hidden: { opacity: 0, y: 40, scale: 0.96 }, visible: { opacity: 1, y: 0, scale: 1, transition: { duration: 0.5, ease: [0.21, 0.47, 0.32, 0.98] } } }; export function CardGrid({ cards }: { cards: { id: number; title: string }[] }) { return ( {cards.map(card => (

{card.title}

 ))} ); } ``` --- ### 8. 3D Tilt on Scroll **Copilot Chat Prompt:** ``` Framer Motion: 3D perspective card that rotates on X axis as it scrolls through view. rotateX 15→0→-15, scale 0.9→1→0.9, opacity 0→1→0. Target ref with offset ['start end', 'end start']. Wrap in perspective container. ``` ```tsx 'use client'; import { useRef } from 'react'; import { motion, useScroll, useTransform } from 'motion/react'; export function TiltCard({ children }: { children: React.ReactNode }) { const ref = useRef(null); const { scrollYProgress } = useScroll({ target: ref, offset: ['start end', 'end start'], }); const rotateX = useTransform(scrollYProgress, [0, 0.5, 1], [15, 0, -15]); const scale = useTransform(scrollYProgress, [0, 0.5, 1], [0.9, 1, 0.9]); const opacity = useTransform(scrollYProgress, [0, 0.2, 0.8, 1], [0, 1, 1, 0]); return (
{children}
); } ``` --- ## Variants Pattern for Stagger Variants propagate automatically from parent to children — you don't need to pass them down manually. ```tsx const parent = { hidden: {}, visible: { transition: { staggerChildren: 0.1, // Delay between each child delayChildren: 0.2, // Initial delay before first child when: 'beforeChildren', // Parent animates before children } } }; const child = { hidden: { opacity: 0, y: 20 }, visible: { opacity: 1, y: 0, transition: { duration: 0.5 } } }; // Children with `variants={child}` automatically get the stagger // when the parent transitions between 'hidden' and 'visible' ``` --- ## Motion Value Events ```tsx import { useScroll, useMotionValueEvent } from 'motion/react'; const { scrollY } = useScroll(); // Fires on every change — use for imperative side effects useMotionValueEvent(scrollY, 'change', latest => { console.log('scroll position:', latest); }); // Detect scroll direction const [direction, setDirection] = useState<'up' | 'down'>('down'); useMotionValueEvent(scrollY, 'change', current => { const diff = current - scrollY.getPrevious()!; setDirection(diff > 0 ? 'down' : 'up'); }); ``` **When to use `useMotionValueEvent` vs `useTransform`:** - Use `useTransform` when you want a CSS value that animates smoothly (y, opacity, color) - Use `useMotionValueEvent` when you want to fire React state changes or side effects --- ## Next.js & App Router Notes ```tsx // Every file using motion hooks must be a Client Component 'use client'; // For page-level scroll tracking in App Router, use useScroll in a layout // that's already a client component — don't try to use it in Server Components // If you need SSR-safe scroll animations, gate with: import { useEffect, useState } from 'react'; const [mounted, setMounted] = useState(false); useEffect(() => setMounted(true), []); if (!mounted) return null; // or a skeleton ``` **Recommended pattern for Next.js App Router:** 1. Keep all `motion.*` components in separate `'use client'` files 2. Import them into Server Components — they'll be client-rendered automatically 3. Use `AnimatePresence` at the layout level for page transitions --- ## Accessibility ```tsx import { useReducedMotion } from 'motion/react'; export function AnimatedCard() { const prefersReducedMotion = useReducedMotion(); return ( Content ); } ``` Or disable all scroll-linked transforms when reduced motion is preferred: ```tsx const prefersReducedMotion = useReducedMotion(); const y = useTransform( scrollYProgress, [0, 1], prefersReducedMotion ? [0, 0] : [100, -100] // no movement if reduced motion ); ``` --- ## Common Copilot Pitfalls **Missing 'use client':** Copilot forgets to add this for Next.js App Router files. Every file using `useScroll`, `useTransform`, `motion.*`, or any hook needs `'use client'` at the top. **Using style prop on a plain div:** Copilot sometimes writes `
` where `y` is a MotionValue. This silently does nothing. Must be ``. **Old import path:** Copilot still generates `from 'framer-motion'` (valid, but legacy). Current canonical: `from 'motion/react'`. **Forgetting offset on useScroll:** Without `offset`, `scrollYProgress` tracks the full page from 0 to 1 — not the element's position. Always pass `target` + `offset` for element-level tracking. **Missing ref on target:** Copilot sometimes writes `target: ref` but forgets to attach `ref` to the DOM element. ```tsx const ref = useRef(null); const { scrollYProgress } = useScroll({ target: ref }); // ← ref passed return
...
; // ← ref attached ``` **Using animate prop for scroll-linked values:** Scroll-linked values must use `style`, not `animate`. `animate` runs on mount/unmount, not on scroll. ```tsx // ❌ Wrong // ✅ Correct ``` **Not smoothing scroll progress:** Raw `scrollYProgress` can feel mechanical on fine motion. Wrap in `useSpring` for progress bars and UI elements that need a polished feel.