Skip to content

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
View the source Spec sheet as Markdown

Install

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).

Your code
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

PropTypeDefaultWhat it does
childrenstringnoneRequired. Plain text string to split and reveal (not JSX).
asReact.ElementType"h1"HTML tag to render as root container.
by"word" | "character" | "line""word"Token granularity for entrance stagger.
delaynumber0Initial delay in ms before animation begins.
staggernumber60Delay in ms between subsequent token animations. Capped at 40 ms when the tier is 1 or lower.
durationnumber400Duration in ms for each token entrance.
classNamestring""Extra classes on the root element (the built-in class fb-text-reveal is kept).
styleReact.CSSPropertiesnoneOptional. No default. Inline styles on the root element, merged after position: relative and display: block (consumer wins).
refReact.Ref<any>noneReceives the root element chosen by `as` (it also contains the scoped <style> and a screen-reader copy of the text).
maxTiernumber3Hard ceiling on the capability tier.
replayKeystring | numbernoneOptional. No default. When set (or changed), the entrance animation plays after hydration even for a server-rendered instance.
pausedbooleanfalseUniversal 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).
noncestringnoneOptional 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.

MeasureResult
Size, gzip3.12 KB at load, 0.02 KB loaded later
Layout shift0
Frames when nothing should moveoff screen 0, hidden tab 0, reduced motion 0
axe accessibility scan0 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.

EnvironmentTierResultDateNotes
Chromium Desktop (SwiftShader)3pass2026-10-2115 passed, 0 failed
Chromium Mobile (Pixel 7 emulation)2pass2026-10-2114 passed, 0 failed
Firefox Desktop3pass2026-10-2114 passed, 0 failed
WebKit Desktop3pass2026-10-2114 passed, 0 failed
WebKit Mobile (iPhone 14 emulation)2pass2026-10-2114 passed, 0 failed

On different devices

Reduced motion (static): Renders plain static text without splitting or animations.

TierWhat it does
T3 FullSame as tier 2; the `by` mode (word, character, line) is honoured at every animated tier
T2 StandardAnimated reveal with the configured stagger (60 ms by default)
T1 LiteAnimated reveal with the stagger capped at 40 ms (coarse pointer with low-end hints)
T0 StaticPlain 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 your nonce), or call initMotionReady() in Vite.
  • Sets inline style attributes, so allow style-src-attr 'unsafe-inline'.

Goes well with