page-provider · Page scroll
SmoothScroll
Smooth, weighted scrolling for a marketing page, off on phones and with reduced motion.
Lenis provider stepped strictly via useFrame with autoRaf false
- Page scroll
- Reduced motion: off
- 2.7 KB gzip
- Layout shift 0
Install
pnpm dlx shadcn@4.21.1 add @frictionborn/smooth-scroll
Playground
import { SmoothScroll } from "@/components/ui/smooth-scroll";
<SmoothScroll>
{children}
</SmoothScroll>In a full example
The full example loads as you scroll to it.
Accessibility
- Native keyboard scrolling is preserved. When reduced motion is preferred, smooth scrolling is turned off completely, delegating all scroll behavior to the native platform compositor.
- Keyboard: Keys (Space, PageUp, PageDown, arrows, Home, End) scroll natively; Lenis does not intercept them and a keydown only wakes the shared frame loop
- Touch: Native touch momentum scrolling is preserved; Lenis is inactive on coarse pointers
- WCAG criteria it is built for: 2.1.1, 2.2.2, 2.3.3
Props
| Prop | Type | Default | What it does |
|---|---|---|---|
children | React.ReactNode | none | Optional. No default. Child components wrapped inside the provider (rendered in a display: contents div). |
duration | number | 1200 | Scroll easing duration in milliseconds (e.g. 1200 means 1.2 seconds). |
paused | boolean | false | Universal pause prop. Freezes kinetic smooth scrolling. |
easing | (t: number) => number | "(t) => Math.min(1, 1.001 - Math.pow(2, -10 * t))" | Easing function (default is a module-level function). Read through a ref, so an inline function does not recreate Lenis. |
orientation | "vertical" | "horizontal" | "vertical" | Primary scroll orientation. |
gestureOrientation | "vertical" | "horizontal" | "both" | "vertical" | Gesture direction Lenis listens to. |
smoothWheel | boolean | true | Whether to interpolate mouse wheel deltas. |
touchMultiplier | number | 1 | Lenis touch multiplier (touch scrolling is not smoothed on coarse pointers because SmoothScroll is disabled there). |
infinite | boolean | false | Lenis infinite scroll option. |
enabled | boolean | true | Master toggle to enable or disable smooth scrolling. |
onScroll | (e: any) => void | none | Called with the Lenis scroll event (not the DOM scroll event, even though the root is a <div>). |
prevent | (node: HTMLElement) => boolean | none | Optional. No default. Predicate to bypass smooth scrolling for specific DOM nodes. Nested scrollers (allowNestedScroll) and [role="dialog"], [aria-modal="true"], dialog[open], [data-lenis-prevent] are always bypassed. |
ref | React.Ref<HTMLDivElement> | none | Receives the root <div>, which is display: contents, so its bounding box is empty (use it for data attributes, not geometry). |
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 | 2.7 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 | 21 passed, 0 failed |
| Chromium Mobile (Pixel 7 emulation) | 2 | pass | 2026-10-21 | 15 passed, 0 failed |
| Firefox Desktop | 3 | pass | 2026-10-21 | 20 passed, 0 failed |
| WebKit Desktop | 3 | pass | 2026-10-21 | 20 passed, 0 failed |
| WebKit Mobile (iPhone 14 emulation) | 2 | pass | 2026-10-21 | 15 passed, 0 failed |
On different devices
Reduced motion (off): Disabled completely; 100% native platform momentum scrolling.
| Tier | What it does |
|---|---|
| T3 Full | Smooth scrolling runs (fine pointer with hover), stepped via useFrame; same behaviour as tier 2 on fine pointers |
| T2 Standard | Coarse pointer: disabled. On a fine or absent pointer (low-end hints or viewport < 480px) smooth scrolling runs, stepped via useFrame |
| T1 Lite | Coarse pointer: disabled, native touch momentum scrolling preserved |
| T0 Static | Not gated by tier. Smooth scrolling runs unless reduced motion, enabled={false} or a coarse pointer disables it; Save-Data and no-WebGL2 (tier 0) do not disable it |
Content Security Policy
- Works without
'unsafe-eval'. - Needs no reveal gate.
- Sets inline
styleattributes, so allowstyle-src-attr 'unsafe-inline'.