# Word-by-Word Reveal

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

## What it is

A word-by-word reveal animates each word of a passage in turn, rather than all at once or letter by letter. Words are how people read, so a delay of roughly 80 to 120 milliseconds per word follows the eye through a sentence: slow enough to feel intentional, fast enough that nobody waits.

## When to use it
- Multi-line body copy, quotes, and paragraph intros where per-letter would be too busy
- Sequential storytelling where you want each phrase to land before the next
- Subtitle or caption reveals timed to a voiceover
- Sectioned reveals where sentence pauses separate distinct thoughts

## How it works
The text is split on whitespace into `<span class="word">` elements, each carrying an `--i` index. The CSS derives a `transition-delay` from `--i × --stagger`, and adding the `.in` class on the container drops every word to its resting state at once — the delays fan the motion out:

```js
words.forEach((w,wi)=>{
  const s=document.createElement('span');s.className='word';
  const delay=punctTog.checked?idx*stagger+si*200:idx*stagger;
  s.style.setProperty('--i',delay/stagger);
  s.textContent=w;target.appendChild(s);
  if(wi<words.length-1)target.appendChild(document.createTextNode(' '));
  idx++;
});
```

```css
.word{display:inline-block;opacity:0;
  transition:opacity var(--dur) var(--ease) calc(var(--i)*var(--stagger)),
             transform var(--dur) var(--ease) calc(var(--i)*var(--stagger))}
[data-anim="fade-up"] .word{transform:translateY(0.4em)}
.splitting.in .word{opacity:1;transform:none;filter:none}
```

The Pauses between sentences switch adds `si × 200ms` to the delay for each sentence, inserting a beat between lines. Because the index is stored as `delay/stagger`, the CSS math stays a single `calc()` regardless of whether pauses are on.

## Key parameters

| Parameter | Default | Effect |
|-----------|---------|--------|
| Delay between words | Medium | The reading-speed control: short is 40ms, medium 80ms and long 150ms; below about 40ms the words blur into one reveal |
| How each word appears | Fade up | The entrance each word plays as it fades in: fade up rises by 0.4 of the font size, fade only fades, grow starts at 60% of its size, blur starts 8px blurred and flip turns in from 90°, edge-on, around a horizontal line |
| Speed | Normal | How long each word takes to settle: slow is 700ms, normal 450ms and fast 270ms |
| Feel | Smooth | Smooth slows each word into place; Springy adds a bounce; Even feels mechanical |
| Pauses between sentences | off | Adds an extra pause between sentences |
| Your text | Three sample sentences | The passage that is revealed, one sentence per line |

## Production notes
- **Whitespace preservation**: keeping a real text node (a literal space) between word spans lets the browser wrap and justify normally, which pure `margin-right` spacing cannot do reliably across fonts.
- **Runtime scales with length**: total time is `wordCount × stagger + dur`. A long paragraph at 120ms/word can run for many seconds — cap the word count or the stagger for anything past a sentence or two.
- **Reduced motion**: the demo collapses to a single 300ms linear fade with no transform when `prefers-reduced-motion` is set, so the content still appears without the sequential motion.
- **GSAP**: `SplitText({type:"words"})` plus `stagger` on a tween is the direct equivalent.
- **Framer Motion**: a container variant with `staggerChildren:0.08` and a per-word child variant reproduces this without manual index math.
- **Motion One**: `stagger(0.08)` passed as the `delay` option to `animate()`.

## See also
- [Letter-by-Letter Stagger](../letter-by-letter-stagger/) — one letter at a time, for short phrases
- [Split Text Reveal](../split-text-reveal/) — text breaks into letters, words or lines
- [Fade In / Fade Out](../fade-in-out/) — the whole text fades in at once
