}
```
- `layout` — animates both position and size
- `layout="position"` — only animates position (prevents text reflow)
- `layout="size"` — only animates size
### Shared layout (element morphing between states)
```tsx
import { LayoutGroup, motion } from "framer-motion";
function Tabs({ tabs, activeTab, onSelect }) {
return (
{tabs.map((tab) => (
))}
);
}
```
`layoutId` — elements with the same `layoutId` morph into each other across mounts/unmounts. Use for tab indicators, card expand/collapse, list reordering.
---
## Pixel's Common Animation Patterns
### 1. Blur Reveal (blur 10px→0px + opacity + y movement)
```tsx
const blurRevealVariants = {
hidden: {
opacity: 0,
y: 20,
filter: "blur(10px)",
},
visible: {
opacity: 1,
y: 0,
filter: "blur(0px)",
transition: {
duration: 0.6,
ease: "easeOut",
filter: { duration: 0.8 }, // blur clears slightly slower
},
},
};
```
### 2. Staggered Grid Entrance (staggerChildren: 0.05)
```tsx
const gridContainerVariants = {
hidden: { opacity: 0 },
visible: {
opacity: 1,
transition: {
staggerChildren: 0.05,
delayChildren: 0.1,
},
},
};
const gridItemVariants = {
hidden: { opacity: 0, y: 20, scale: 0.95 },
visible: {
opacity: 1,
y: 0,
scale: 1,
transition: {
type: "spring",
stiffness: 300,
damping: 24,
},
},
};
{items.map((item) => (
))}
```
### 3. Count-Up Numbers
```tsx
"use client";
import { useEffect, useRef, useState } from "react";
import {
useInView,
useMotionValue,
useTransform,
motion,
animate,
} from "framer-motion";
function CountUp({
target,
duration = 2,
suffix = "",
prefix = "",
}: {
target: number;
duration?: number;
suffix?: string;
prefix?: string;
}) {
const ref = useRef(null);
const isInView = useInView(ref, { once: true, margin: "-100px" });
const motionValue = useMotionValue(0);
const rounded = useTransform(motionValue, (v) => Math.round(v));
const [display, setDisplay] = useState(0);
useEffect(() => {
if (!isInView) return;
const controls = animate(motionValue, target, {
duration,
ease: "easeOut",
});
const unsubscribe = rounded.on("change", (v) => setDisplay(v));
return () => {
controls.stop();
unsubscribe();
};
}, [isInView, target, duration, motionValue, rounded]);
return (
{prefix}{display.toLocaleString()}{suffix}
);
}
// Usage
// "10,000+"
// "99%"
// rounds to integers
```
### 4. Card Hover Lift (y: -2, shadow increase)
```tsx
const cardHoverVariants = {
rest: {
y: 0,
boxShadow: "0 1px 3px rgba(0,0,0,0.08)",
transition: { type: "spring", stiffness: 400, damping: 25 },
},
hover: {
y: -2,
boxShadow: "0 8px 25px rgba(0,0,0,0.12)",
transition: { type: "spring", stiffness: 400, damping: 25 },
},
};
```
### 5. Page Transitions (exit opacity→0, enter opacity→1 with mode="wait")
```tsx
// app/template.tsx
"use client";
import { AnimatePresence, motion } from "framer-motion";
import { usePathname } from "next/navigation";
const pageVariants = {
initial: { opacity: 0, y: 8 },
enter: {
opacity: 1,
y: 0,
transition: { duration: 0.3, ease: "easeOut" },
},
exit: {
opacity: 0,
y: -8,
transition: { duration: 0.2, ease: "easeIn" },
},
};
export default function Template({ children }: { children: React.ReactNode }) {
const pathname = usePathname();
return (
{children}
);
}
```
---
## Reduced Motion (Accessibility — Required)
Always provide `prefers-reduced-motion` fallbacks. Users with vestibular disorders need this.
### useReducedMotion hook
```tsx
import { useReducedMotion } from "framer-motion";
function AnimatedCard({ children }: { children: React.ReactNode }) {
const shouldReduceMotion = useReducedMotion();
return (
{children}
);
}
```
### Global reduced motion wrapper
```tsx
// components/motion-wrapper.tsx
"use client";
import { useReducedMotion } from "framer-motion";
import { createContext, useContext } from "react";
const ReducedMotionContext = createContext(false);
export function MotionProvider({ children }: { children: React.ReactNode }) {
const shouldReduceMotion = useReducedMotion() ?? false;
return (
{children}
);
}
export function useMotionSafe() {
const shouldReduceMotion = useContext(ReducedMotionContext);
return {
shouldReduceMotion,
// Returns static values if reduced motion preferred
entrance: shouldReduceMotion
? { initial: { opacity: 0 }, animate: { opacity: 1 }, transition: { duration: 0.01 } }
: undefined, // let caller define full animation
};
}
```
### CSS fallback (always include alongside framer-motion)
```css
@media (prefers-reduced-motion: reduce) {
*, *::before, *::after {
animation-duration: 0.01ms !important;
animation-iteration-count: 1 !important;
transition-duration: 0.01ms !important;
scroll-behavior: auto !important;
}
}
```
---
## Performance Rules
1. **Use `viewport={{ once: true }}`** on scroll-triggered animations — prevents re-triggering on scroll up
2. **Avoid animating `width`/`height`** — use `scale`, `opacity`, `x`, `y` (GPU-composited properties)
3. **Use `layout` sparingly** — layout animations are expensive; only use when needed
4. **Use `will-change: transform`** on elements with continuous animations (parallax)
5. **Don't animate filter on large elements** — `blur()` is expensive; keep blur-reveal elements small or use short durations
6. **Unmount animated components** — use `AnimatePresence` to cleanly unmount, don't just hide with CSS
7. **Avoid stagger on 50+ items** — stagger 20+ items gets sluggish; paginate or virtualize
---
## Next.js App Router Integration Notes
- All motion components require `"use client"` directive
- `AnimatePresence` with page transitions goes in `template.tsx` (not `layout.tsx` — layouts don't re-mount)
- Server Components can import client motion components as children
- For SSR hydration: `initial` prop prevents flash-of-unstyled on hydration
- Framer Motion v11+ supports React 18+ and React Server Components (as long as motion usage is in client components)
---
## Common Gotchas
| Issue | Cause | Fix |
|-------|-------|-----|
| Exit animations don't play | Missing `AnimatePresence` wrapper | Wrap conditional render in `AnimatePresence` |
| Content invisible on load | `initial` opacity 0, `whileInView` but element already in viewport | Add `animate` fallback or check viewport on mount |
| Stagger not working | Children missing `variants` prop | Children must use `variants`, not inline `animate` |
| Layout animation glitchy | Animating between very different layouts | Use `layout="position"` instead of `layout` |
| Hydration mismatch | Motion values differ server vs client | Use `initial={false}` to skip initial animation |
| Page transition flicker | Using `layout.tsx` instead of `template.tsx` | Move `AnimatePresence` to `template.tsx` |