Smooth scrolling to anchors, elements and positions that lands where it should: below fixed headers, centered in strips or at the nearest edge, with easing, interruption, focus, history and a promise for when it arrives. For vanilla JavaScript, any framework and plain HTML.
Demo · Examples · Documentation · Changelog
- Installation
- Quick start
- HTML / CDN
- Capabilities
- API at a glance
- Documentation
- Changelog
- AI agent skill
- License
npm install @samline/scroll-topnpm add @samline/scroll-tobun add @samline/scroll-toAny modern browser; without JavaScript, links still jump to their sections. On the server, every function is inert. No runtime dependencies.
import { autoScrollTo } from '@samline/scroll-to'
autoScrollTo({ offset: '#header' })<header id="header">
<a href="#pricing">Pricing</a>
</header>
<section id="pricing">…</section>
<button type="button" data-scroll-to="top">Back to top</button>From your own code:
import { scrollTo } from '@samline/scroll-to'
const arrived = await scrollTo('#faq', { offset: '#header', duration: 600 })Follow it while it runs:
scrollTo('#faq', {
offset: '#header',
onProgress: ({ eased }) => bar.style.setProperty('--progress', eased),
onEnd: ({ reason }) => console.log(reason), // 'arrived', 'interrupted', …
})For Shopify, WordPress or plain HTML pages without a build step, load the browser bundle. It handles same-page #id links and [data-scroll-to] as soon as the DOM is ready. Pin the version in production.
<script
src="https://cdn.jsdelivr.net/npm/@samline/scroll-to@1.6.0/dist/browser/scroll-to.global.js"
defer
></script>Any element with data-scroll-to-back-to-top becomes a back-to-top button; style its [data-scroll-to-visible="false"] state to hide it near the top.
<a class="back-to-top" href="#top" data-scroll-to-back-to-top>Back to top</a>The bundle defines window.ScrollTo. Add data-manual to the script tag and call ScrollTo.auto(options) to start it with your own options.
Keep space for a fixed header with offset: pixels, a percentage, the header element measured live, 'auto' to find every fixed and sticky bar stuck at the top, or 'css' to reuse your scroll-padding-top. Offsets add up in arrays. Align to the start, center, end or nearest edge on both axes, skip the scroll when the target is already visible with when: 'needed', and land precisely even when images load on the way: the destination is measured on every frame.
Sections and hidden answers
Step through sections with data-scroll-to="next" and "prev": quick presses add up. Links to content inside a closed <details> or a hidden="until-found" panel open it first, like the browser's own fragment links. Each link can set its own focus, hash and reveal.
Scroll to 'bottom', move relatively with '+=100%', page through a strip with { left: '+=100%' }, and time it with a duration, a constant speed or a maxDuration. Easing takes a name, any CSS cubic-bezier() or your own function.
Links move keyboard focus to their target on arrival and push the #id to the URL, so Tab continues from there and Back returns. Reduced motion jumps instead of animating.
The wheel, a touch, a key that scrolls or a press on the scrollbar stops the scroll at once, while pressing Next again or tabbing does not, and a new scroll replaces the running one. Every scroll returns a promise of true (arrived) or false (interrupted).
onStart, onProgress and onEnd follow a scroll from its first frame to its end, and onEnd says why it ended: arrived, interrupted, replaced, cancelled or missing. The same moments bubble as scroll-to:start and scroll-to:end events, and data-scroll-to-state="scrolling" marks the trigger and the scrolling element while it runs, so plain HTML and CSS can react too. Stop a scroll from anywhere with an AbortSignal.
highlight marks the target with data-scroll-to-arrived for a moment once it arrives, and --scroll-to-progress follows a running scroll from 0 to 1 on the trigger and the scrolling element, so CSS can flash the target or fill a bar. backToTop(button) shows a button once the page is scrolled one screen down, exposes --scroll-to-scrolled for a progress ring, and moves focus to the top when pressed. With the CDN script, data-scroll-to-back-to-top does it without code.
queue: true waits for the running scroll instead of replacing it, so scrolls can follow one another. scrollSequence from @samline/scroll-to/sequence walks through a list of stops with play, pause, next, prev, loop and a pause per step, and pauses itself when the visitor takes over: tours, demos and kiosks.
createScrollTo({ offset: '#header' }) returns a scroller with shared options for every call, its own auto() for links, and one destroy() that stops what it started.
Scroll the page or any box, and center the selected tab of a horizontal strip without moving the page. container: 'auto' scrolls every box around the target and then the page in one animation, like scrollIntoView with an offset. Scroll snapping is paused while it moves, CSS scroll-behavior: smooth never doubles the glide, and right-to-left strips align and step in reading order. Triggers can carry their own offset, container, alignment and duration as attributes.
| API | Purpose |
|---|---|
autoScrollTo(options?) |
Handle same-page links and [data-scroll-to] with one listener. Returns { destroy }. |
scrollTo(target, options?) |
Scroll to an element, #id, selector, 'top' or position. Resolves true on arrival. |
scrollPosition(target, options?) |
Where it would scroll, without moving. |
cancelScroll(container?) |
Stop the running scroll. |
isScrolling(container?) |
Whether a scroll is running. |
createScrollTo(defaults?) |
A scroller with shared options: { to, position, cancel, isScrolling, auto, destroy }. |
onStart, onProgress, onEnd |
Options that follow a scroll; onEnd gets { arrived, reason, top, left, target }. |
signal |
An AbortSignal that stops the scroll. |
offset: 'auto' | 'css' | [...] |
Find stuck headers, read CSS scroll padding, or add offsets up. |
when: 'needed' |
Skip the scroll when the target is already visible. |
speed, maxDuration, easing |
Pace by pixels per second; easing takes names, cubic-bezier() or a function. |
cubicBezier(x1, y1, x2, y2) |
The easing function of a CSS curve. |
'next', 'prev', sections |
Step to the next or previous section. |
highlight |
Mark the target with data-scroll-to-arrived on arrival, for a CSS highlight. |
backToTop(button, options?) |
A back-to-top button with data-scroll-to-visible and --scroll-to-scrolled. |
container: 'auto' |
Scroll every box around the target, then the page, in one animation. |
queue |
Wait for the running scroll instead of replacing it. |
scrollSequence(steps, options?) |
A guided tour: { play, pause, toggle, next, prev, goTo, destroy }. |
reveal |
Open closed <details> and hidden="until-found" around the target (default true). |
scroll-to:start, scroll-to:end |
Bubbling events on the target, with the same details as the callbacks. |
| Entrypoint | When to use |
|---|---|
@samline/scroll-to |
ESM or CommonJS, every function. |
@samline/scroll-to/vanilla |
scrollTo as the default export. |
@samline/scroll-to/sequence |
scrollSequence for guided tours. |
@samline/scroll-to/browser |
Classic script that defines window.ScrollTo. |
Read the documentation for the full guides and API contracts, and explore working examples with complete and separate source files.
| Guide | What it covers |
|---|---|
| Installation | npm, CDN and the first links. |
| API reference | Every function, createScrollTo, the events, the types and window.ScrollTo. |
| Options | Options, targets and attributes. |
| Layouts | Fixed headers, skip links, nested boxes, scroll snap, right to left, tabs and history. |
| Aim and timing | Every offset, relative targets and points, when, speed, durations and easing. |
| Sections | Next and previous, hidden content, per-link focus and hash, and what stops a scroll. |
| Lifecycle | Callbacks, end reasons, events, the state attribute, AbortSignal and createScrollTo. |
| Feedback | Highlight on arrival, --scroll-to-progress, and a back-to-top button with a ring. |
| Sequences | queue, and guided tours with scrollSequence: play, pause, steps and loop. |
| Frameworks | React, Vue, Svelte, Astro and client-side routers. |
Read CHANGELOG.md or the published changelog for release history and explicitly marked breaking and behavior changes. Review the notes before upgrading.
The Scroll To skill teaches verified package integration. Its maintained repository source and website download are the same file. Verify the installed package version before applying its guidance.
Download SKILL.md into a scroll-to/ folder in your agent's supported skill directory. For agents that discover project skills from .agents/skills/:
mkdir -p .agents/skills/scroll-to
curl --fail --location https://samline.github.io/scroll-to/skills/scroll-to/SKILL.md \
--output .agents/skills/scroll-to/SKILL.mdKeep the filename SKILL.md; discovery paths and invocation syntax depend on the agent.
MIT — LICENSE.md.