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
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.
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
| Prop | Type | Default | What it does |
|---|---|---|---|
children | React.ReactNode | none | Required. Content elements wrapped and revealed on scroll. |
as | React.ElementType | "div" | HTML tag rendered as root container. |
animation | "fade-up" | "fade" | "scale-up" | "fade-up" | Visual entrance variant. |
distance | number | 24 | Vertical travel distance in pixels (half of it for scale-up); capped at 12 when the tier is 1 or lower. |
duration | number | 400 | Transition duration in ms. Applies only to the IntersectionObserver fallback; the native view-timeline animation is scroll-linked and ignores it. |
once | boolean | true | In 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. |
className | string | "" | Extra classes on the root element (the built-in class fb-scroll-reveal is kept). |
style | React.CSSProperties | none | Optional. No default. Inline styles on the root element, merged after display: block and position: relative (consumer wins). |
ref | React.Ref<any> | none | Receives the root element chosen by `as`. |
maxTier | number | 3 | Hard ceiling on the capability tier. |
paused | boolean | false | Universal 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. |
nonce | string | none | Optional 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.
| Measure | Result |
|---|---|
| Size, gzip | 1.98 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 | 14 passed, 0 failed |
| Chromium Mobile (Pixel 7 emulation) | 2 | pass | 2026-10-21 | 13 passed, 0 failed |
| Firefox Desktop | 3 | pass | 2026-10-21 | 13 passed, 0 failed |
| WebKit Desktop | 3 | pass | 2026-10-21 | 13 passed, 0 failed |
| WebKit Mobile (iPhone 14 emulation) | 2 | pass | 2026-10-21 | 13 passed, 0 failed |
On different devices
Reduced motion (static): Content is rendered in its final visible state without transition delays or scroll triggers.
| Tier | What it does |
|---|---|
| T3 Full | Same 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 Standard | Reveal with the configured travel distance (24px by default) |
| T1 Lite | Reveal with the travel distance capped at 12px (coarse pointer with low-end hints) |
| T0 Static | Content 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 yournonce), or callinitMotionReady()in Vite. - Sets inline
styleattributes, so allowstyle-src-attr 'unsafe-inline'.