Smooth Scroll · paneui

offset 0pxprogress 0%native

Monday

Dentist at 9:30, then the quarterly review with finance.

Tuesday

Groceries arrive between 6 and 7pm. Gym class at 8.

Wednesday

Lunch with Mei near the office. Pick up dry cleaning.

Thursday

Flight to Tokyo held until noon — confirm or release.

Friday

Dinner booked for four at 7:30. Flowers for Mum ordered.

Saturday

Farmers market, then nothing at all. Keep it that way.

Sunday

Meal prep and the weekly plan. Call home in the evening.

Installation

pnpm dlx shadcn@latest add @paneui/smooth-scroll

Usage

import { SmoothScroll } from "@/components/ui/smooth-scroll"

<SmoothScroll className="h-80">
  <Article />
</SmoothScroll>

Examples

Horizontal

Use for galleries and timelines that scroll sideways.

Lerp vs Duration

Scroll to Section

Scrollbars

Contained mode scrolls in a Scroll Area: thin overlay bars inside the frame that follow the eased position. container points at its viewport.

Motion

Under reduced motion nothing is eased, so scrolling is native and scrollTo jumps instead of animating. Touch scrolling stays native unless you set touch.

Scroll Progress, Scroll To and Scroll Reveal read this provider.

API Reference

SmoothScroll

Eased scroll container (or, with root, a provider that eases the window). Also accepts every prop of div.

root= false: boolean; true eases the whole page and renders only the provider. false renders its own scroll container; give it a height.
lerp= 0.1: number; Smoothing per frame, 0–1. Lower is heavier. Ignored when duration is set.
duration: number; Fixed ease duration in seconds for wheel and programmatic scrolls.
orientation= "vertical": "vertical" | "horizontal"; Scroll axis.
wheelMultiplier= 1: number; Multiplies wheel deltas.
touch= false: boolean; Ease touch scrolling too. Off by default so phones keep native momentum.
contentClassName: string; Class for the inner content element (contained mode only).

Prop	Type	Default	Description
root	boolean	false	`true` eases the whole page and renders only the provider. `false` renders its own scroll container; give it a height.
lerp	number	0.1	Smoothing per frame, 0–1. Lower is heavier. Ignored when `duration` is set.
duration	number	—	Fixed ease duration in seconds for wheel and programmatic scrolls.
orientation	"vertical" \| "horizontal"	"vertical"	Scroll axis.
wheelMultiplier	number	1	Multiplies wheel deltas.
touch	boolean	false	Ease touch scrolling too. Off by default so phones keep native momentum.
contentClassName	string	—	Class for the inner content element (contained mode only).

data-smooth: Present on the container while it is eased.

Data attribute	Description
data-smooth	Present on the container while it is eased.

useSmoothScroll

Scroll state for the nearest SmoothScroll. Outside a provider it falls back to the window's native scroll.

lenis: Lenis | null; The easing instance, or null on the native or reduced-motion path.
smooth: boolean; Whether scrolling is currently eased.
container: RefObject<HTMLElement | null> | null; The scroll container, or null for the window.
offset: MotionValue<number>; Current scroll offset in px.
progress: MotionValue<number>; Scroll position from 0 (start) to 1 (end).
velocity: MotionValue<number>; Signed scroll velocity in px per frame.
scrollTo: (target: number | string | HTMLElement, options?: { offset?: number; duration?: number; immediate?: boolean }) => void; Scroll to a px offset, selector or element. Jumps under reduced motion.

Prop	Type	Default	Description
lenis	Lenis \| null	—	The easing instance, or `null` on the native or reduced-motion path.
smooth	boolean	—	Whether scrolling is currently eased.
container	RefObject<HTMLElement \| null> \| null	—	The scroll container, or `null` for the window.
offset	MotionValue<number>	—	Current scroll offset in px.
progress	MotionValue<number>	—	Scroll position from 0 (start) to 1 (end).
velocity	MotionValue<number>	—	Signed scroll velocity in px per frame.
scrollTo	(target: number \| string \| HTMLElement, options?: { offset?: number; duration?: number; immediate?: boolean }) => void	—	Scroll to a px offset, selector or element. Jumps under reduced motion.

useSmoothScrollContainer

The nearest SmoothScroll's container ref, or null for the window or no provider. Pass it to motion's useScroll({ container }).