Guide

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

  1. 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 }.
  2. Its destination is computed for the container (the page by default), the alignment (block, inline) and the offset, and clamped to what can scroll. With when: 'needed', a target already in view stays where it is.
  3. The scroll is animated with duration (or speed) and easing. The destination is measured again on every frame, so images that load on the way do not make it land in the wrong place.
  4. Closed <details> and hidden="until-found" content around the target opens first.
  5. 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.
  6. On arrival, links move keyboard focus to the target and push its #id to the URL, like a native jump. With highlight, the target is marked with data-scroll-to-arrived for a moment.
  7. It ends exactly once, with a reason: arrived, interrupted, replaced, cancelled or missing.

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

JobHow
Smooth anchor linksautoScrollTo(), or the CDN script
Any element as a triggerdata-scroll-to="#id", a selector or top
Clear a fixed headeroffset: pixels, %, the header, 'auto' or 'css'
Alignblock and inline: start, center, end, nearest
Scroll a box or stripcontainer
Boxes inside boxescontainer: 'auto'
Speed and feelduration, speed, maxDuration and easing
Relative moves'+=100%', 'bottom', { left: '+=100%' }
Skip when visiblewhen: 'needed'
Step through sectionsdata-scroll-to="next" / "prev", sections
Reach hidden answersClosed <details> open on their own (reveal)
From codeawait scrollTo(target, options)
Measure onlyscrollPosition(target, options)
Follow itonStart, 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 landedhighlight and [data-scroll-to-arrived]
Back to topbackToTop(button) or data-scroll-to-back-to-top
Stop it from anywheresignal (an AbortSignal) or cancelScroll()
Wait for the running onequeue: true
Guided toursscrollSequence from @samline/scroll-to/sequence
Share optionscreateScrollTo(defaults)

Choose your next step