Skip to content

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

Install

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

Playground

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

PropTypeDefaultWhat it does
childrenReact.ReactNodenoneOptional. No default. Child components wrapped inside the provider (rendered in a display: contents div).
durationnumber1200Scroll easing duration in milliseconds (e.g. 1200 means 1.2 seconds).
pausedbooleanfalseUniversal 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.
smoothWheelbooleantrueWhether to interpolate mouse wheel deltas.
touchMultipliernumber1Lenis touch multiplier (touch scrolling is not smoothed on coarse pointers because SmoothScroll is disabled there).
infinitebooleanfalseLenis infinite scroll option.
enabledbooleantrueMaster toggle to enable or disable smooth scrolling.
onScroll(e: any) => voidnoneCalled with the Lenis scroll event (not the DOM scroll event, even though the root is a <div>).
prevent(node: HTMLElement) => booleannoneOptional. 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.
refReact.Ref<HTMLDivElement>noneReceives 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.

MeasureResult
Size, gzip2.7 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-2121 passed, 0 failed
Chromium Mobile (Pixel 7 emulation)2pass2026-10-2115 passed, 0 failed
Firefox Desktop3pass2026-10-2120 passed, 0 failed
WebKit Desktop3pass2026-10-2120 passed, 0 failed
WebKit Mobile (iPhone 14 emulation)2pass2026-10-2115 passed, 0 failed

On different devices

Reduced motion (off): Disabled completely; 100% native platform momentum scrolling.

TierWhat it does
T3 FullSmooth scrolling runs (fine pointer with hover), stepped via useFrame; same behaviour as tier 2 on fine pointers
T2 StandardCoarse pointer: disabled. On a fine or absent pointer (low-end hints or viewport < 480px) smooth scrolling runs, stepped via useFrame
T1 LiteCoarse pointer: disabled, native touch momentum scrolling preserved
T0 StaticNot 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 style attributes, so allow style-src-attr 'unsafe-inline'.

Goes well with