# Letter-by-Letter Stagger

[Live demo](https://matinmonshizadeh.github.io/animation-handbook/animations/02-entrance-and-exit/letter-by-letter-stagger/)

## What it is

A letter-by-letter stagger animates each character a moment after the previous one, so a phrase assembles as a cascade instead of appearing all at once. The demo shows two versions: a cascade where every letter plays a small entrance, and a typewriter that reveals letters one at a time, with an optional blinking cursor.

## When to use it
- Hero headlines and landing-page titles where the text is the focal point
- Short phrases under ~30 characters — the effect is dramatic and gets tedious on long copy
- Loading or "assembling" states that want to feel deliberate
- Typewriter mode specifically for terminal UIs, chat interfaces, and code demos

## How it works
Each character is wrapped in its own `<span class="char">` and given a custom property `--i` equal to its index. The CSS multiplies that index by a `--stagger` value to compute a per-letter `transition-delay`, so letter *n* starts `n × stagger` milliseconds after the animation is triggered:

```js
[...text].forEach((c,i)=>{
  const s=document.createElement('span');
  s.className='char';s.style.setProperty('--i',i);
  s.textContent=c===' '?'\u00a0':c; // a lone plain space would collapse inside its inline-block
  target.appendChild(s);
});
```

```css
[data-mode="cascade"] .char{
  opacity:0;
  transition:opacity var(--dur) var(--ease) calc(var(--i)*var(--stagger)),
             transform var(--dur) var(--ease) calc(var(--i)*var(--stagger));
}
[data-mode="cascade"][data-anim="fade-up"] .char{transform:translateY(0.4em)}
[data-mode="cascade"].done .char{opacity:1;transform:none}
```

Adding the `.done` class flips every letter to its resting state simultaneously; the staggered `transition-delay` is what spreads the visible motion out over time. The typewriter mode skips transitions entirely and instead uses a chain of `setTimeout` calls to toggle a `.visible` class on each character in sequence.

## Key parameters

| Parameter | Default | Effect |
|-----------|---------|--------|
| Style | Cascade | Cascade animates every letter in turn; Typewriter types them out |
| Delay between letters | Medium | The gap between letters: short is 20ms, medium 35ms and long 80ms; higher is slower and more theatrical |
| How each letter appears | Fade up | In Cascade, the entrance each letter plays as it fades in: fade up rises by 0.4 of the font size, fade only fades, grow starts at 30% of its size and flip turns in from 90°, edge-on, around a vertical line |
| Speed | Normal | In Cascade, how long each letter takes to settle: slow is 650ms, normal 400ms and fast 250ms |
| Blinking cursor | on | In Typewriter, a blinking cursor leads the letters |
| Your text | Hello, world. | The phrase that is animated, up to 60 characters |

## Production notes
- **Accessibility**: split text still reads as separate spans to most screen readers, but wrapping the whole phrase in an `aria-label` on the container and hiding the spans with `aria-hidden` guarantees the label is announced as one string. The demo honors `prefers-reduced-motion` by forcing all letters visible with no transition.
- **Layout cost**: `display:inline-block` on each span is required for `transform` to apply, but it disables normal line-breaking within words. For wrapping headlines, split on words first, then letters inside each word.
- **Don't overuse**: per-letter is the most granular split and the most quickly grating. Reserve it for one headline per page.
- **GSAP**: `SplitText` plus a `stagger` value on a timeline is the canonical implementation and handles the wrapping-span bookkeeping for you.
- **Framer Motion**: use a parent `variants` object with `staggerChildren`, mapping each letter to a child `motion.span`.
- **Motion One**: pass an array of elements to `animate()` with a `delay: stagger(0.035)` helper.

## See also
- [Word-by-Word Reveal](../word-by-word-reveal/) — one word at a time, better for longer text
- [Split Text Reveal](../split-text-reveal/) — text breaks into letters, words or lines
- [Blur In](../blur-in/) — sharpens from a blur as it fades in
