easing-scroll

Programmatic smooth scrolling with custom easing, abort support, and promise-based completion tracking.

Demo

Highlights

• Zero dependencies — ~450 bytes min+gzip
• TypeScript-first — written in TypeScript, ships type declarations
• Dual package — ESM and CJS builds
• Customizable — bring your own easing function
• Cancellable — abort with AbortSignal
• Promise-based — await completion or track partial progress
• Universal — works with any scrollable Element

Install

npm install easing-scroll

pnpm add easing-scroll

Quick Start

import { easingScroll } from "easing-scroll";

const container = document.querySelector(".container");

await easingScroll(container, {
  top: 300,
  duration: 400,
  easing: (x) => 1 - Math.pow(1 - x, 3), // easeOutCubic
});

API

easingScroll(target, options): Promise<number>

Smoothly scrolls target to the given position.

target

Type: Element

Any scrollable DOM element.

options

Option	Type	Default	Description
top	number	—	Target vertical scroll position in pixels
left	number	—	Target horizontal scroll position in pixels
duration	number	0	Animation duration in milliseconds
easing	(t: number) => number	(t) => t	Easing function mapping progress (0–1) to eased value
signal	AbortSignal	—	Signal to cancel the animation

Return value

Resolves with a number between 0 and 1 representing animation progress:

Value	Meaning
1	Animation completed fully
0 < x < 1	Animation was aborted at x progress
0	Animation never started (signal was already aborted)

Behavior

• Instant scroll — when duration is 0 or negative, the element scrolls instantly and resolves 1.
• No-op — when both top and left are omitted, resolves 1 immediately.
• Clamping — scroll values are clamped to the element's scrollable range. No visual flash occurs.
• Already-aborted signal — resolves 0 without scrolling.

Examples

Custom Easing

The default easing is linear (t) => t. Pass any function from easings.net:

await easingScroll(element, {
  top: 500,
  duration: 600,
  // https://easings.net/#easeOutCubic
  easing: (x) => 1 - Math.pow(1 - x, 3),
});

Abort Scrolling

Use an AbortController to cancel an in-flight animation:

const controller = new AbortController();

setTimeout(() => controller.abort(), 100);

const progress = await easingScroll(element, {
  top: 1000,
  duration: 400,
  signal: controller.signal,
});

if (progress < 1) {
  console.log(`Aborted at ${Math.round(progress * 100)}%`);
}

React Hook

A reusable hook that cancels the previous scroll when dependencies change or the component unmounts:

import { useEffect, RefObject } from "react";
import { easingScroll } from "easing-scroll";

function useEasingScroll(ref: RefObject<HTMLElement | null>, top: number) {
  useEffect(() => {
    const target = ref.current;
    if (!target) return;

    const controller = new AbortController();

    easingScroll(target, {
      top,
      duration: 400,
      signal: controller.signal,
      easing: (x) => 1 - Math.pow(1 - x, 3),
    });

    return () => controller.abort();
  }, [top]);
}

License

MIT