smooth-auto-scroll


React hook and component for smooth auto-scroll. Perfect for continuous scrolling at any speed with buttery-smooth motion.

> ⚛️ React Only: This library requires React 17+ and uses React hooks. For vanilla JS or other frameworks, you'll need a different solution.

🚀 Try the Interactive Demo

Experience all the features live with customizable controls and real-time code generation.

Install

``bash
npm i smooth-auto-scroll


peer: react


`

Usage

> 💡 See it in action: Interactive Demo with live controls and code examples.

`tsx
import { AutoScrollContainer } from "smooth-auto-scroll";





;
`

Hook

`tsx
import { useSmoothAutoScroll } from "smooth-auto-scroll";

const containerRef = useRef(null);
const innerRef = useRef(null);

useSmoothAutoScroll({ containerRef, innerRef, pxPerSecond: 5 });
`

API

$3

- pxPerSecond: number — scroll speed in pixels per second (required)
- enabled: boolean — enable/disable scrolling, default true
- containerRef: React.RefObject — scroll container ref (hook only, required)
- innerRef: React.RefObject — inner content ref (hook only, required)

$3

- capDtMs: number — frame delta cap in milliseconds, default 16.67 (~60fps)
- smoothingFactor: number — velocity smoothing factor, default 0.1
- accelerationTime: number — time to reach full speed in ms, default 1000

- respectReducedMotion: boolean — respect user's reduced motion preference, default true

$3

- bottomTolerance: number — pixels from bottom to stop, default 1
- topTolerance: number — pixels from top to stop, default 1
- startOffset: number — pixels from top before starting, default 0
- endOffset: number — pixels from bottom before stopping, default 0

$3

- direction: "down" | "up" — scroll direction, default "down"

$3

- pauseEvents: Array — events that pause scrolling, default ["wheel", "touchmove", "keydown", "mousedown", "focus"]
- resumeEvents: Array — events that resume scrolling, default ["mouseleave", "touchend", "touchcancel"]
- pauseOnHover: boolean — pause when mouse enters container, default false
- pauseOnFocus: boolean — pause when container receives focus, default false
- resumeDelay: number — delay in ms before resuming after user interaction, default 0

$3

- onStart: () => void — called when scrolling starts
- onPause: () => void — called when scrolling pauses
- onResume: () => void — called when scrolling resumes
- onReachEnd: () => void — called when reaching bottom/end
- onReachTop: () => void — called when reaching top

$3

- containerRef: React.RefObject — optional external container ref
- className: string — CSS class for container
- style: React.CSSProperties — inline styles for container
- children: React.ReactNode — content to scroll

$3

- Pauses on specified user events; resumes on specified resume events or visibility change
- Supports any DOM event for both pauseEvents and resumeEvents (e.g., "click", "mousedown", "touchstart", "mouseleave", "keyup")
- Uses hardware acceleration for ultra-smooth motion at any speed
- Automatically handles reduced motion preferences when respectReducedMotion is enabled

Examples

$3

`tsx
// Only pause on wheel events
pxPerSecond={5}
pauseEvents={["wheel"]}
>
{content}


// Pause on multiple events
pxPerSecond={5}
pauseEvents={["wheel", "touchstart", "mousedown", "keydown"]}
>
{content}


// Never pause on user events (only on hover/focus if enabled)
pxPerSecond={5}
pauseEvents={[]}
>
{content}

`

$3

`tsx
// Resume on mouse click
pxPerSecond={5}
pauseEvents={["wheel", "keydown"]}
resumeEvents={["click"]}
>
{content}


// Resume on multiple events
pxPerSecond={5}
pauseEvents={["wheel", "touchmove"]}
resumeEvents={["mouseleave", "keyup", "touchend"]}
>
{content}


// Never resume on user events (only programmatically)
pxPerSecond={5}
resumeEvents={[]}
>
{content}

``