headline · HTML and CSS
TextReveal
Headlines that arrive word by word, line by line or letter by letter, with the full text always readable.
word/line/char text reveal
- HTML and CSS
- Reduced motion: static
- 3.12 KB gzip
- Layout shift 0
Install
pnpm dlx shadcn@4.21.1 add @frictionborn/text-reveal
Playground
Every change replays the reveal. On a server-rendered page the first load shows the finished text (no flash).
import { TextReveal } from "@/components/ui/text-reveal";
<TextReveal as="h2">
Friction makes heat, heat makes a spark.
</TextReveal>In a full example
The full example loads as you scroll to it.
Accessibility
- Original text is preserved in a visually-hidden span while animated tokens are marked aria-hidden='true', ensuring screen readers never read fragmented letters or words.
- Keyboard: None; the text is not focusable. It stays selectable. Screen readers read a visually hidden copy of the full text; the animated tokens are aria-hidden.
- Touch: Same as pointer; the stagger is capped at 40 ms only on tier 1 and tier 0 devices
- WCAG criteria it is built for: 1.3.1, 1.4.3, 2.2.2
Props
| Prop | Type | Default | What it does |
|---|---|---|---|
children | string | none | Required. Plain text string to split and reveal (not JSX). |
as | React.ElementType | "h1" | HTML tag to render as root container. |
by | "word" | "character" | "line" | "word" | Token granularity for entrance stagger. |
delay | number | 0 | Initial delay in ms before animation begins. |
stagger | number | 60 | Delay in ms between subsequent token animations. Capped at 40 ms when the tier is 1 or lower. |
duration | number | 400 | Duration in ms for each token entrance. |
className | string | "" | Extra classes on the root element (the built-in class fb-text-reveal is kept). |
style | React.CSSProperties | none | Optional. No default. Inline styles on the root element, merged after position: relative and display: block (consumer wins). |
ref | React.Ref<any> | none | Receives the root element chosen by `as` (it also contains the scoped <style> and a screen-reader copy of the text). |
maxTier | number | 3 | Hard ceiling on the capability tier. |
replayKey | string | number | none | Optional. No default. When set (or changed), the entrance animation plays after hydration even for a server-rendered instance. |
paused | boolean | false | Universal pause prop. Renders plain static text instead of the animated tokens; un-pausing replays the reveal from the start (it does not freeze mid-animation). |
nonce | string | none | Optional CSP nonce forwarded to the internal scoped <style> element. |
Measured on the bench
Measured by the automated bench at commit 801163e on 2026-10-21. These numbers are written by the bench, never by hand.
| Measure | Result |
|---|---|
| Size, gzip | 3.12 KB at load, 0.02 KB loaded later |
| Layout shift | 0 |
| Frames when nothing should move | off screen 0, hidden tab 0, reduced motion 0 |
| axe accessibility scan | 0 serious, 0 critical |
Browsers it ran in
Automated Playwright runs, some with device emulation. Results from physical phones and tablets are still pending, so none are listed.
| Environment | Tier | Result | Date | Notes |
|---|---|---|---|---|
| Chromium Desktop (SwiftShader) | 3 | pass | 2026-10-21 | 15 passed, 0 failed |
| Chromium Mobile (Pixel 7 emulation) | 2 | pass | 2026-10-21 | 14 passed, 0 failed |
| Firefox Desktop | 3 | pass | 2026-10-21 | 14 passed, 0 failed |
| WebKit Desktop | 3 | pass | 2026-10-21 | 14 passed, 0 failed |
| WebKit Mobile (iPhone 14 emulation) | 2 | pass | 2026-10-21 | 14 passed, 0 failed |
On different devices
Reduced motion (static): Renders plain static text without splitting or animations.
| Tier | What it does |
|---|---|
| T3 Full | Same as tier 2; the `by` mode (word, character, line) is honoured at every animated tier |
| T2 Standard | Animated reveal with the configured stagger (60 ms by default) |
| T1 Lite | Animated reveal with the stagger capped at 40 ms (coarse pointer with low-end hints) |
| T0 Static | Plain static text, no splitting (server render, prefers-reduced-motion, Save-Data, or no WebGL2) |
Content Security Policy
- Works without
'unsafe-eval'. - Uses the reveal gate (
[data-motion="ok"]): render<MotionReadyScript />in<head>(with yournonce), or callinitMotionReady()in Vite. - Sets inline
styleattributes, so allowstyle-src-attr 'unsafe-inline'.