Scrol

A small deterministic engine for programmatic scrolling and target reveal.

import { createScrollEngine } from "scroller2"

const scroll = createScrollEngine()

await scroll.reveal(target, {
  block: "nearest",
  visibility: "full",
  safeArea: { top: 64, right: 320, bottom: 32, left: 32 },
  motion: "smooth",
})

Install with pnpm add scroller2.

The engine discovers axis-aware scroll ancestors, plans each reveal as immutable data, then executes inner-to-outer with a geometry refresh between surfaces. It supports instant, tween, and lerp motion, external RAF, cancellation, retargeting, and scroll settlement.

API

scroll.planReveal(target, options)
scroll.reveal(target, options)
scroll.to(surface, { x, y }, options)
scroll.by(surface, { x, y }, options)
scroll.getState(surface)
scroll.raf(time)
scroll.destroy()

Set autoRaf: false when another runtime owns the frame clock. Call scroll.raf(time) from that clock until the returned operation settles.

Development

Run pnpm test for the pure planner and runtime tests, and pnpm build for the ESM package. After building, serve the repository root and open playground/index.html to compare motion across 100–3000px distances.