Smooth auto-scroll React hook and component for ultra-smooth motion at any speed.
npm install 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.
Experience all the features live with customizable controls and real-time code generation.
``bash`
npm i smooth-auto-scrollpeer: react
> 💡 See it in action: Interactive Demo with live controls and code examples.
`tsx
import { AutoScrollContainer } from "smooth-auto-scroll";
...your content...
`
`tsx
import { useSmoothAutoScroll } from "smooth-auto-scroll";
const containerRef = useRef
const innerRef = useRef
useSmoothAutoScroll({ containerRef, innerRef, pxPerSecond: 5 });
`
- pxPerSecond: number — scroll speed in pixels per second (required)enabled
- : boolean — enable/disable scrolling, default truecontainerRef
- : React.RefObjectinnerRef
- : React.RefObject
- capDtMs: number — frame delta cap in milliseconds, default 16.67 (~60fps)smoothingFactor
- : number — velocity smoothing factor, default 0.1accelerationTime
- : number — time to reach full speed in ms, default 1000
- respectReducedMotion: boolean — respect user's reduced motion preference, default true
- bottomTolerance: number — pixels from bottom to stop, default 1topTolerance
- : number — pixels from top to stop, default 1startOffset
- : number — pixels from top before starting, default 0endOffset
- : number — pixels from bottom before stopping, default 0
- direction: "down" | "up" — scroll direction, default "down"
- pauseEvents: Array["wheel", "touchmove", "keydown", "mousedown", "focus"]resumeEvents
- : Array["mouseleave", "touchend", "touchcancel"]pauseOnHover
- : boolean — pause when mouse enters container, default falsepauseOnFocus
- : boolean — pause when container receives focus, default falseresumeDelay
- : number — delay in ms before resuming after user interaction, default 0
- onStart: () => void — called when scrolling startsonPause
- : () => void — called when scrolling pausesonResume
- : () => void — called when scrolling resumesonReachEnd
- : () => void — called when reaching bottom/endonReachTop
- : () => void — called when reaching top
- containerRef: React.RefObjectclassName
- : string — CSS class for containerstyle
- : React.CSSProperties — inline styles for containerchildren
- : React.ReactNode — content to scroll
- 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")respectReducedMotion
- Uses hardware acceleration for ultra-smooth motion at any speed
- Automatically handles reduced motion preferences when is enabled
`tsx
// Only pause on wheel events
pauseEvents={["wheel"]}
>
{content}
// Pause on multiple events
pauseEvents={["wheel", "touchstart", "mousedown", "keydown"]}
>
{content}
// Never pause on user events (only on hover/focus if enabled)
pauseEvents={[]}
>
{content}
`
`tsx
// Resume on mouse click
pauseEvents={["wheel", "keydown"]}
resumeEvents={["click"]}
>
{content}
// Resume on multiple events
pauseEvents={["wheel", "touchmove"]}
resumeEvents={["mouseleave", "keyup", "touchend"]}
>
{content}
// Never resume on user events (only programmatically)
resumeEvents={[]}
>
{content}
``