1# Animations
2 
3Interruptible animations, enter/exit transitions, and contextual icon animations.
4 
5## Interruptible Animations
6 
7Users change intent mid-interaction. If animations aren't interruptible, the interface feels broken.
8 
9### CSS Transitions vs. Keyframes
10 
11| | CSS Transitions | CSS Keyframe Animations |
12| --- | --- | --- |
13| **Behavior** | Interpolate toward latest state | Run on a fixed timeline |
14| **Interruptible** | Yes — retargets mid-animation | No — restarts from beginning |
15| **Use for** | Interactive state changes (hover, toggle, open/close) | Staged sequences that run once (enter animations, loading) |
16| **Duration** | Adapts to remaining distance | Fixed regardless of state |
17 
18```css
19/* Good — interruptible transition for a toggle */
20.drawer {
21  transform: translateX(-100%);
22  transition: transform 200ms ease-out;
23}
24.drawer.open {
25  transform: translateX(0);
26}
27 
28/* Clicking again mid-animation smoothly reverses — no jank */
29```
30 
31```css
32/* Bad — keyframe animation for interactive element */
33.drawer.open {
34  animation: slideIn 200ms ease-out forwards;
35}
36 
37/* Closing mid-animation snaps or restarts — feels broken */
38```
39 
40**Rule:** Always prefer CSS transitions for interactive elements. Reserve keyframes for one-shot sequences.
41 
42## Enter Animations: Split and Stagger
43 
44Don't animate a single large container. Break content into semantic chunks and animate each individually.
45 
46### Step by Step
47 
481. **Split** into logical groups (title, description, buttons)
492. **Stagger** with ~100ms delay between groups
503. **For titles**, consider splitting into individual words with ~80ms stagger
514. **Combine** `opacity`, `blur`, and `translateY` for the enter effect
52 
53### Code Example
54 
55```tsx
56// Motion (Framer Motion) — staggered enter
57function PageHeader() {
58  return (
59    <motion.div
60      initial="hidden"
61      animate="visible"
62      variants={{
63        visible: { transition: { staggerChildren: 0.1 } },
64      }}
65    >
66      <motion.h1
67        variants={{
68          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
69          visible: { opacity: 1, y: 0, filter: "blur(0px)" },
70        }}
71      >
72        Welcome
73      </motion.h1>
74 
75      <motion.p
76        variants={{
77          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
78          visible: { opacity: 1, y: 0, filter: "blur(0px)" },
79        }}
80      >
81        A description of the page.
82      </motion.p>
83 
84      <motion.div
85        variants={{
86          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
87          visible: { opacity: 1, y: 0, filter: "blur(0px)" },
88        }}
89      >
90        <Button>Get started</Button>
91      </motion.div>
92    </motion.div>
93  );
94}
95```
96 
97### CSS-Only Stagger
98 
99```css
100.stagger-item {
101  opacity: 0;
102  transform: translateY(12px);
103  filter: blur(4px);
104  animation: fadeInUp 400ms ease-out forwards;
105}
106 
107.stagger-item:nth-child(1) { animation-delay: 0ms; }
108.stagger-item:nth-child(2) { animation-delay: 100ms; }
109.stagger-item:nth-child(3) { animation-delay: 200ms; }
110 
111@keyframes fadeInUp {
112  to {
113    opacity: 1;
114    transform: translateY(0);
115    filter: blur(0);
116  }
117}
118```
119 
120## Exit Animations
121 
122Exit animations should be softer and less attention-grabbing than enter animations. The user's focus is moving to the next thing — don't fight for attention.
123 
124### Subtle Exit (Recommended)
125 
126```tsx
127// Small fixed translateY — indicates direction without drama
128<motion.div
129  exit={{
130    opacity: 0,
131    y: -12,
132    filter: "blur(4px)",
133    transition: { duration: 0.15, ease: "easeIn" },
134  }}
135>
136  {content}
137</motion.div>
138```
139 
140### Full Exit (When Context Matters)
141 
142```tsx
143// Slide fully out — use when spatial context is important
144// (e.g., a card returning to a list, a drawer closing)
145<motion.div
146  exit={{
147    opacity: 0,
148    x: "-100%",
149    transition: { duration: 0.2, ease: "easeIn" },
150  }}
151>
152  {content}
153</motion.div>
154```
155 
156### Good vs. Bad
157 
158```css
159/* Good — subtle exit */
160.item-exit {
161  opacity: 0;
162  transform: translateY(-12px);
163  transition: opacity 150ms ease-in, transform 150ms ease-in;
164}
165 
166/* Bad — dramatic exit that steals focus */
167.item-exit {
168  opacity: 0;
169  transform: translateY(-100%) scale(0.5);
170  transition: all 400ms ease-in;
171}
172 
173/* Bad — no exit animation at all (element just vanishes) */
174.item-exit {
175  display: none;
176}
177```
178 
179**Key points:**
180- Use a small fixed `translateY` (e.g., `-12px`) instead of the full container height
181- Keep some directional movement to indicate where the element went
182- Exit duration should be shorter than enter duration (150ms vs 300ms)
183- Don't remove exit animations entirely — subtle motion preserves context
184 
185## Contextual Icon Animations
186 
187When icons appear or disappear contextually (on hover, on state change), animate them with `opacity`, `scale`, and `blur` rather than just toggling visibility.
188 
189### Motion Example
190 
191```tsx
192import { AnimatePresence, motion } from "motion/react";
193 
194function IconButton({ isActive, icon: Icon }) {
195  return (
196    <button>
197      <AnimatePresence mode="popLayout">
198        <motion.span
199          key={isActive ? "active" : "inactive"}
200          initial={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
201          animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}
202          exit={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
203          transition={{ type: "spring", duration: 0.3, bounce: 0 }}
204        >
205          <Icon />
206        </motion.span>
207      </AnimatePresence>
208    </button>
209  );
210}
211```
212 
213### CSS Transition Approach (No Motion)
214 
215If the project doesn't use Motion (Framer Motion), keep both icons in the DOM and cross-fade them with CSS transitions. Because neither icon unmounts, both enter and exit animate smoothly.
216 
217The trick: one icon is absolutely positioned on top of the other. Toggling state cross-fades them — the entering icon scales up from `0.25` while the exiting icon scales down to `0.25`, both with opacity and blur.
218 
219```tsx
220function IconButton({ isActive, ActiveIcon, InactiveIcon }) {
221  return (
222    <button>
223      <div className="relative">
224        <div
225          className={cn(
226            "absolute inset-0 flex items-center justify-center",
227            "transition-[opacity,filter,scale] duration-300",
228            "cubic-bezier(0.2, 0, 0, 1)",
229            isActive
230              ? "scale-100 opacity-100 blur-0"
231              : "scale-[0.25] opacity-0 blur-[4px]"
232          )}
233        >
234          <ActiveIcon />
235        </div>
236        <div
237          className={cn(
238            "transition-[opacity,filter,scale] duration-300",
239            "cubic-bezier(0.2, 0, 0, 1)",
240            isActive
241              ? "scale-[0.25] opacity-0 blur-[4px]"
242              : "scale-100 opacity-100 blur-0"
243          )}
244        >
245          <InactiveIcon />
246        </div>
247      </div>
248    </button>
249  );
250}
251```
252 
253The non-absolute icon (InactiveIcon) defines the layout size. The absolute icon (ActiveIcon) overlays it without affecting flow.
254 
255### Choosing Between Motion and CSS
256 
257| | Motion (Framer Motion) | CSS transitions (both icons in DOM) |
258| --- | --- | --- |
259| **Enter animation** | Yes | Yes |
260| **Exit animation** | Yes (via `AnimatePresence`) | Yes (cross-fade — icon never unmounts) |
261| **Spring physics** | Yes | No — use `cubic-bezier(0.2, 0, 0, 1)` as approximation |
262| **When to use** | Project already uses `motion/react` | No motion dependency, or keeping bundle small |
263 
264**Rule:** Check the project's `package.json` for `motion` or `framer-motion`. If present, use the Motion approach. If not, use the CSS cross-fade pattern — don't add a dependency just for icon transitions.
265 
266### When to Animate Icons
267 
268| Animate | Don't animate |
269| --- | --- |
270| Icons that appear on hover (action buttons) | Static navigation icons |
271| State change icons (play → pause, like → liked) | Decorative icons |
272| Icons in contextual toolbars | Icons that are always visible |
273| Loading/success state indicators | Icon labels (text next to icon) |
274 
275**Important:** Always use exactly these values for contextual icon animations — do not deviate:
276- `scale`: `0.25` → `1` (never use `0.5` or `0.6`)
277- `opacity`: `0` → `1`
278- `filter`: `"blur(4px)"` → `"blur(0px)"`
279- `transition`: `{ type: "spring", duration: 0.3, bounce: 0 }` — **bounce must always be `0`**, never `0.1` or any other value
280 
281## Scale on Press
282 
283A subtle scale-down on click gives buttons tactile feedback. Always use `scale(0.96)`. Never use a value smaller than `0.95` — anything below feels exaggerated. Use CSS transitions for interruptibility — if the user releases mid-press, it should smoothly return.
284 
285Not every button needs this. Add a `static` prop to your button component that disables the scale effect when the motion would be distracting.
286 
287### CSS Example
288 
289```css
290.button {
291  transition-property: scale;
292  transition-duration: 150ms;
293  transition-timing-function: ease-out;
294}
295 
296.button:active {
297  scale: 0.96;
298}
299```
300 
301### Tailwind Example
302 
303```tsx
304<button className="transition-transform duration-150 ease-out active:scale-[0.96]">
305  Click me
306</button>
307```
308 
309### Motion Example
310 
311```tsx
312<motion.button whileTap={{ scale: 0.96 }}>
313  Click me
314</motion.button>
315```
316 
317### Static Prop Pattern
318 
319Extract the scale class into a variable and conditionally apply it based on a `static` prop:
320 
321```tsx
322const tapScale = "active:not-disabled:scale-[0.96]";
323 
324function Button({ static: isStatic, className, children, ...props }) {
325  return (
326    <button
327      className={cn(
328        "transition-transform duration-150 ease-out",
329        !isStatic && tapScale,
330        className,
331      )}
332      {...props}
333    >
334      {children}
335    </button>
336  );
337}
338 
339// Usage
340<Button>Click me</Button>           {/* scales on press */}
341<Button static>Submit</Button>       {/* no scale */}
342```
343 
344## Skip Animation on Page Load
345 
346Use `initial={false}` on `AnimatePresence` to prevent enter animations from firing on first render. Elements that are already in their default state shouldn't animate in on page load — only on subsequent state changes.
347 
348### When It Works
349 
350```tsx
351// Good — icon doesn't animate in on mount, only on state change
352<AnimatePresence initial={false} mode="popLayout">
353  <motion.span
354    key={isActive ? "active" : "inactive"}
355    initial={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
356    animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}
357    exit={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
358  >
359    <Icon />
360  </motion.span>
361</AnimatePresence>
362```
363 
364Works well for: icon swaps, toggles, tabs, segmented controls — anything that has a default state on page load.
365 
366### When It Breaks
367 
368Don't use `initial={false}` when the component relies on its `initial` prop to set up a first-time enter animation, like a staggered page hero or a loading state. In those cases, removing the initial animation skips the entire entrance.
369 
370```tsx
371// Bad — initial={false} would skip the staggered page enter entirely
372<AnimatePresence initial={false}>
373  <motion.div initial="hidden" animate="visible" variants={...}>
374    ...
375  </motion.div>
376</AnimatePresence>
377```
378 
379Verify the component still looks right on a full page refresh before applying this.
380