- Docs
Scroll To
What @samline/scroll-to does, how a scroll is aimed, animated and finished, and how links, triggers and containers fit together.
@samline/scroll-to scrolls smoothly to anchors, elements and positions, and stops where it should: below a fixed header, centered in a strip, or at the nearest edge. Call autoScrollTo() (or load the CDN script) and same-page #id links and [data-scroll-to] triggers use it.
<a href="#pricing">Pricing</a> <a href="#top" data-scroll-to-back-to-top>Back to top</a>
How a scroll works
- The target is resolved: an element, an
#id, a selector, a'next'or'prev'section,'top','bottom', a position in pixels, a relative position such as'+=400'or a point{ top, left }. - Its destination is computed for the container (the page by default), the alignment (
block,inline) and theoffset, and clamped to what can scroll. Withwhen: 'needed', a target already in view stays where it is. - The scroll is animated with
duration(orspeed) andeasing. The destination is measured again on every frame, so images that load on the way do not make it land in the wrong place. - Closed
<details>andhidden="until-found"content around the target opens first. - The wheel, a touch, a key that scrolls, a press on the scrollbar or a new scroll on the same container stops it. Reduced motion jumps instead.
- On arrival, links move keyboard focus to the target and push its
#idto the URL, like a native jump. Withhighlight, the target is marked withdata-scroll-to-arrivedfor a moment. - It ends exactly once, with a reason:
arrived,interrupted,replaced,cancelledormissing.
scrollTo() returns a promise of true when it arrives and false otherwise. onStart, onProgress and onEnd, the scroll-to:start and scroll-to:end events, the data-scroll-to-state attribute and the --scroll-to-progress custom property follow it while it runs.
Pieces
| Job | How |
|---|---|
| Smooth anchor links | autoScrollTo(), or the CDN script |
| Any element as a trigger | data-scroll-to="#id", a selector or top |
| Clear a fixed header | offset: pixels, %, the header, 'auto' or 'css' |
| Align | block and inline: start, center, end, nearest |
| Scroll a box or strip | container |
| Boxes inside boxes | container: 'auto' |
| Speed and feel | duration, speed, maxDuration and easing |
| Relative moves | '+=100%', 'bottom', { left: '+=100%' } |
| Skip when visible | when: 'needed' |
| Step through sections | data-scroll-to="next" / "prev", sections |
| Reach hidden answers | Closed <details> open on their own (reveal) |
| From code | await scrollTo(target, options) |
| Measure only | scrollPosition(target, options) |
| Follow it | onStart, onProgress, onEnd, or scroll-to:* events |
| Style it while it runs | [data-scroll-to-state='scrolling'] |
| A bar that fills with it | --scroll-to-progress, from 0 to 1 |
| Show where it landed | highlight and [data-scroll-to-arrived] |
| Back to top | backToTop(button) or data-scroll-to-back-to-top |
| Stop it from anywhere | signal (an AbortSignal) or cancelScroll() |
| Wait for the running one | queue: true |
| Guided tours | scrollSequence from @samline/scroll-to/sequence |
| Share options | createScrollTo(defaults) |
Choose your next step
Package managers, the CDN and the first links.
ExamplesLive previews with the complete, copyable source of each one.
API referenceSignatures and behavior of scrollTo, scrollPosition, cancelScroll, autoScrollTo and window.ScrollTo.
Options and attributes.
Layouts and focusFixed headers, skip links, nested boxes, scroll snap, right to left, tabs and history.
Aim and timingOffsets, CSS scroll padding, sticky bars, relative targets, speed and easing.
Sections and hidden contentNext and previous, closed details, per-link focus and hash, and what stops a scroll.
Lifecycle and eventsCallbacks, end reasons, events, the state attribute, AbortSignal and createScrollTo.
Highlight and back to topHighlight the target on arrival, a progress property, and a back-to-top button with a ring.
Queues and guided toursScrolls that wait their turn, and tours that play, pause and step.
Accessibility and motionFocus, reduced motion and what your page provides.
Framework integrationsReact, Vue, Svelte, Astro and client-side routers.