scroll-scrubbed-word-reveal

Scroll-Scrubbed Word Reveal

Make reading progress visible without replacing real text, breaking inline markup, or depending on a fixed line count.

Prepare the text

1. Keep one untouched accessible text source in the DOM.
2. Walk text nodes with TreeWalker; do not flatten the container with textContent or innerHTML.
3. Skip script, style, form controls, and elements marked with [data-no-split].
4. Replace only non-whitespace tokens with spans and preserve whitespace nodes exactly.
5. Mark generated spans aria-hidden="true" only when an equivalent unsplit accessible copy remains available.

Preferred structure:

<p class="reveal" data-reveal>
  Motion should <em>explain</em> the next state, not decorate it.
</p>

Avoid line-based splitting. Browser line wraps must remain free to change with container width, language, zoom, and font loading.

Map scroll to words

Use section progress as the single source of truth:

const reveal = Math.min(1, Math.max(0, progress));
const local = Math.min(1, Math.max(0, reveal * wordCount - index));
word.style.setProperty("--word-progress", local);

Interpolate hidden opacity, blur, and vertical offset from --word-progress. Keep the visible state identical to normal typography.

Use GSAP ScrollTrigger with scrub when precise starts, ends, refresh, or a shared timeline is needed. Use a dependency-free scroll measurement plus requestAnimationFrame for a standalone section.

Set useful defaults

• Hidden opacity: 0.12–0.3
• Blur: 4–10px
• Vertical offset: 0.08–0.22em
• Reveal span: 120–220% of the viewport for a paragraph
• Direct word overlap: 10–30%
• Easing: none for the scroll mapping; ease only the visual interpolation when needed

Expose the values as CSS custom properties. Scale the scroll span from text length rather than assuming one duration fits every passage.

Preserve emphasis

• Let links, strong, em, marks, and accent spans keep their semantics and styling.
• Use inherited color by default; style accents on the original element, not on token indexes.
• Do not reveal essential links only on hover or after the reader has passed them.
• Re-split only when the source text changes. Responsive wrapping does not require rebuilding tokens.
• Store enough state to restore the original DOM during cleanup.