scroll-into-area

Smooth scrolling an element into a specific position within a scrollable container, with custom easing, abort support, and promise-based completion tracking.

Demo

Highlights

• Lightweight — built on top of easing-scroll
• TypeScript-first — written in TypeScript, ships type declarations
• Dual package — ESM and CJS builds
• Positioning — align to start, center, end, or nearest on both axes
• Offset — compensate for sticky headers/footers with the offset option
• Customizable — bring your own easing function
• Cancellable — abort with AbortSignal
• Promise-based — await completion or track partial progress

Install

npm install scroll-into-area

pnpm add scroll-into-area

Quick Start

import { scrollIntoArea } from "scroll-into-area";

const container = document.querySelector("ul");
const target = container.querySelector("li");

await scrollIntoArea(target, {
  container,
  y: "center",
  duration: 400,
  easing: (x) => 1 - Math.pow(1 - x, 3), // easeOutCubic
});

API

scrollIntoArea(target, options): Promise<number>

Smoothly scrolls target into a specific position within the scrollable container.

target

Type: Element

The DOM element to scroll into view.

options

| Option | Type | Default | Description | | ----------- | ----------------------- | ---------- | ---------------------------------------------------------------------------- | | container | HTMLElement | — | The scrollable container element (required) | | x | Position | — | Horizontal alignment: "start", "center", "end", or "nearest" | | y | Position | — | Vertical alignment: "start", "center", "end", or "nearest" | | 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 | | offset | number | 0 | Offset in pixels from the alignment edge (useful for sticky headers/footers) |

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 omitted, the element scrolls instantly and resolves 1.
• No-op — when both x and y are omitted, resolves 1 immediately.
• Already-aborted signal — resolves 0 without scrolling.
• Nearest — "nearest" only scrolls when the target is outside the visible area. If the target is larger than the container, it aligns to start.
• Offset — creates inward space from the alignment edge. For "start" and "center", the target is pushed away from the start edge. For "end", the target is pushed away from the end edge. For "nearest", narrows the visible area used for detection.

Examples

Custom Easing

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

await scrollIntoArea(target, {
  container,
  y: "start",
  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 scrollIntoArea(target, {
  container,
  y: "center",
  duration: 400,
  signal: controller.signal,
});

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

React Usage

A reusable hook that scrolls an element into view and cancels on unmount:

import { useEffect, useRef } from "react";
import { scrollIntoArea, type Position } from "scroll-into-area";

function useScrollIntoArea(
  containerRef: React.RefObject<HTMLElement | null>,
  targetRef: React.RefObject<Element | null>,
  y: Position,
) {
  useEffect(() => {
    const container = containerRef.current;
    const target = targetRef.current;
    if (!container || !target) return;

    const controller = new AbortController();

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

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

Types

The library exports the Position type for use in your own abstractions:

import { type Position } from "scroll-into-area";
// Position = "start" | "end" | "center" | "nearest"

License

MIT