Skip to content

media · HTML and CSS

ScrollReveal

Content that rises into place as it scrolls into view, and is simply there without JavaScript.

Scroll-driven entrance (CSS view() timeline, IntersectionObserver fallback)

  • HTML and CSS
  • Reduced motion: static
  • 1.98 KB gzip
  • Layout shift 0
View the source Spec sheet as Markdown

Install

Install
pnpm dlx shadcn@4.21.1 add @frictionborn/scroll-reveal

Playground

Each change remounts the card, so it reveals again as it enters view.

Your code
import { ScrollReveal } from "@/components/ui/scroll-reveal";

<ScrollReveal>
  <div>Your card or section</div>
</ScrollReveal>

In a full example

The full example loads as you scroll to it.

Accessibility

  • Focus guard forces any element containing active focus visible immediately, preventing keyboard traps during scroll. Hidden-before-reveal styles exist only under html[data-motion="ok"]; server HTML and reduced-motion users see the content visible.
  • Keyboard: Focus-within guard forces element visible immediately when tabbed into
  • Touch: Same scroll trigger; the travel distance is capped at 12px 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
childrenReact.ReactNodenoneRequired. Content elements wrapped and revealed on scroll.
asReact.ElementType"div"HTML tag rendered as root container.
animation"fade-up" | "fade" | "scale-up""fade-up"Visual entrance variant.
distancenumber24Vertical travel distance in pixels (half of it for scale-up); capped at 12 when the tier is 1 or lower.
durationnumber400Transition duration in ms. Applies only to the IntersectionObserver fallback; the native view-timeline animation is scroll-linked and ignores it.
oncebooleantrueIn the IntersectionObserver fallback, true keeps the content revealed after the first entry. The native view-timeline path is scroll-linked and reverses when scrolling back up regardless of this prop.
classNamestring""Extra classes on the root element (the built-in class fb-scroll-reveal is kept).
styleReact.CSSPropertiesnoneOptional. No default. Inline styles on the root element, merged after display: block and position: relative (consumer wins).
refReact.Ref<any>noneReceives the root element chosen by `as`.
maxTiernumber3Hard ceiling on the capability tier.
pausedbooleanfalseUniversal pause prop. Forces the content visible and still. Where the browser supports CSS scroll-driven animation the reveal is driven by the scroll position and this prop has no effect.
noncestringnoneOptional CSP nonce forwarded to the internal scoped <style> element (one is rendered per instance).

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, gzip1.98 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-2114 passed, 0 failed
Chromium Mobile (Pixel 7 emulation)2pass2026-10-2113 passed, 0 failed
Firefox Desktop3pass2026-10-2113 passed, 0 failed
WebKit Desktop3pass2026-10-2113 passed, 0 failed
WebKit Mobile (iPhone 14 emulation)2pass2026-10-2113 passed, 0 failed

On different devices

Reduced motion (static): Content is rendered in its final visible state without transition delays or scroll triggers.

TierWhat it does
T3 FullSame as tier 2. At every animated tier, browsers that support animation-timeline use the scroll-linked CSS animation; others use the IntersectionObserver fallback. The observer hook is mounted in both cases.
T2 StandardReveal with the configured travel distance (24px by default)
T1 LiteReveal with the travel distance capped at 12px (coarse pointer with low-end hints)
T0 StaticContent fully visible and static, no reveal classes (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