- Docs
- Changelog
Changelog
Every @samline/scroll-to release, newest first, with breaking changes, behavior changes and upgrade steps called out explicitly.
All notable changes to this package. Format: Keep a Changelog; versions follow semver.
[1.6.0] - 2026-11-19
Added
queue: true(anddata-scroll-to-queue) waits for the running scroll on the container, and the ones already waiting, instead of replacing it. A scroll withoutqueueends the waiting ones asreplaced, an interruption asinterrupted, andcancelScroll()or an abortedsignalascancelled, all without moving.scrollSequence(steps, options?)in a new entry,@samline/scroll-to/sequence(andScrollTo.scrollSequencein the browser bundle): guided tours through a list of targets or{ target, pause, ...options }steps, withplay,pause,toggle,next,prev,goTo,loop,autoplay, a pause per step,onChange({ index, playing, step })and an idempotentdestroy(). It pauses itself when the visitor takes over or another scroll replaces its own.- Types
SequenceStep,ScrollSequenceOptions,SequenceStateandScrollSequence. - Documentation: a Queues and guided tours guide, and a Guided tour example.
Changed
- Size budgets: 6.4 KB gzip for the package, 5.3 KB for
@samline/scroll-to/sequenceand 7 KB for the browser bundle, which now includesscrollSequence(from 6.2 and 6.3 KB).
[1.5.0] - 2026-11-18
Added
container: 'auto'(anddata-scroll-to-container="auto") scrolls every ancestor of the target that scrolls, then the page, in one animation, likescrollIntoViewwith this package’s offset, easing, focus and hash. Theoffsetapplies to the outermost container,when: 'needed'is decided for each one, callbacks report the innermost container, andcancelScroll()orisScrolling()on any of them sees the scroll.- Right-to-left containers and pages:
inline: 'start'and'end'follow the reading direction,'next'and'prev'step in reading order, and horizontal positions are clamped to the negative range browsers use. - Documentation: nested boxes, scroll snap, right to left and CSS
scroll-behaviorin the Layouts guide, and a Nested boxes example.
Changed
scroll-snap-typeis turned off on the containers a scroll moves while it runs, and restored when it ends, so snapping strips and pages no longer stutter or pull the scroll back.- A target that is already in place arrives without calling
scrollTo()on its container. - Inline styles the package added and removed (
--scroll-to-progress, the paused snap) no longer leave an emptystyleattribute behind. - Size budgets: 6.2 KB gzip for the package and 6.3 KB for the browser bundle (from 5.6 and 5.7 KB).
[1.4.0] - 2026-11-18
Added
highlight(truefor 1500 ms, or a number of milliseconds) setsdata-scroll-to-arrivedon the target once it arrives, so CSS can show where the visitor landed. Arriving again restarts the time; scrolls that do not arrive leave it alone.data-scroll-to-highlightsets it per trigger.--scroll-to-progress: while a scroll runs, the scrolling element and the trigger carry the eased progress from0to1as an inline custom property, removed when it ends, for bars and fills without JavaScript.backToTop(button, options?)returns{ update, destroy }: the button getsdata-scroll-to-visible('true'pastthreshold, by default one screen) and--scroll-to-scrolled(how far down the container is, from0to1) for a progress ring; a click scrolls totarget(the top by default) and moves focus there when the button had it. The browser bundle turns[data-scroll-to-back-to-top]elements into these buttons, with the attribute’s value as the threshold, andScrollTo.backToTopis exposed.- Constants
ARRIVED_ATTRIBUTE,VISIBLE_ATTRIBUTE,PROPERTIESandHIGHLIGHT_DURATION, and the typesBackToTopOptionsandBackToTopController. - Documentation: a Highlight and back to top guide, and two examples, Highlight and Back to top.
Changed
- Size budgets: 5.6 KB gzip for the package and 5.7 KB for the browser bundle (from 4.8 and 4.9 KB).
[1.3.0] - 2026-11-18
Added
'next'and'prev'targets step to the next or previous section, in HTML (data-scroll-to="next") and in code.sections(anddata-scroll-to-sections) chooses what counts as a section; the default is'section'. Sections are compared by where the container would scroll to, with the offset and alignment, so sections it cannot move to are skipped, and a press while a scroll heads to a section steps on from that section.reveal(defaulttrue): before scrolling, closed<details>around the target open (unless the target is in their summary), andhidden="until-found"ancestors receive abeforematchevent and are shown, like the browser does for fragment links.data-scroll-to-reveal="false"andreveal: falseturn it off.- Trigger attributes
data-scroll-to-focusanddata-scroll-to-hash(push,replace,false) set focus and history per link. - Documentation: a Sections and hidden content guide, a Stop button in the Follow the scroll example, and two examples, Next and previous, and Hidden answers.
Changed
- Interruptions: only input that takes over the scroll stops it. The wheel and touch still do; keys only when they scroll (arrows, Page Up, Page Down, Home, End, Space), and mouse presses only outside links, buttons and form controls. Tab, Enter and pressing a trigger again no longer stop a scroll, so a Stop button now ends it as
cancelledthroughcancelScroll()or asignal. - Targets inside closed
<details>andhidden="until-found"content are revealed before the scroll (seereveal). - Size budgets: 4.8 KB gzip for the package and 4.9 KB for the browser bundle (from 4.2 and 4.3 KB).
[1.2.0] - 2026-11-18
Added
offset: 'auto'keeps space for what will cover the top of the container once the target arrives: fixed elements at the top edge and anything stuck below them, and sticky elements with atopthat come before the target, even when they are not stuck yet. Measured on every frame. Elements taller than half of the container (overlays, backdrops) are ignored.offset: 'css'reads the container’sscroll-padding-topand the target’sscroll-margin-top, so the CSS that aligns the browser’s own jumps also aligns the script’s.offsettakes a function,({ container, target }) => number, and an array of offsets that are added up, such as['#header', 16].- Targets:
'bottom', relative positions ('+=400','-=50%', a percentage of the container height) fixed when the scroll starts, and points on both axes ({ top, left }, with{ left: '+=100%' }to page through a strip). when: 'needed'does not move when the target element is already fully visible below the offset; it still resolves totrue, moves focus and writes the hash.speed(pixels per second) andmaxDurationfor'auto'durations.- Easing:
'cubic-bezier(x1, y1, x2, y2)'strings, thecubicBezier()function, and theease-in,ease-out-quintandease-out-backcurves. - Trigger attributes
data-scroll-to-speed,data-scroll-to-easinganddata-scroll-to-when;data-scroll-to-offsetacceptsautoandcss, anddata-scroll-toacceptsbottomand relative positions. - Types:
ScrollPoint,ScrollCoordinate,OffsetValue,OffsetContextandEasingValue. - Documentation: an Aim and timing guide, and two examples, Stacked bars and Page a strip.
Changed
- An invalid selector as
offsetcounts as0instead of throwing. - Size budgets: 4.2 KB gzip for the package and 4.3 KB for the browser bundle (from 3.2 and 3.3 KB).
[1.1.0] - 2026-11-18
Added
onStart,onProgressandonEndoptions follow a scroll from its first frame to its end.onProgressreceivesprogress(time) andeased(distance), andonEndreceivesarrivedand areason:'arrived','interrupted','replaced','cancelled'or'missing'. Every detail carriestarget,container,trigger(the clicked element, withautoScrollTo) and the currenttopandleft.signaloption: anAbortSignalthat stops the scroll. An already aborted signal does not start one, nor replace the running scroll.- Bubbling
scroll-to:startandscroll-to:endevents on the target (or the scrolling element for positions and missing targets), with the same details as the callbacks. data-scroll-to-state="scrolling"on the scrolling element (<html>for the page) and on the clicked trigger while a scroll runs.isScrolling(container?)tells a scroll started by the package from the visitor’s own.createScrollTo(defaults)returns a scroller with shared options:{ to, position, cancel, isScrolling, auto, destroy }.destroy()stops only the scrolls it started and itsauto()controllers.ScrollTo.isScrollingandScrollTo.createScrollToon the browser global;EVENTS,END_REASONSandSTATE_ATTRIBUTEconstants, and theScrollDetail,ScrollProgress,ScrollResult,ScrollEndReasonandScrollToInstancetypes.- Documentation: a Lifecycle and events guide, and two examples, Follow the scroll and Events and state.
Changed
- Size budgets: 3.2 KB gzip for the package and 3.3 KB for the browser bundle (from 2.5 and 2.6 KB).
[1.0.1] - 2026-11-17
Fixed
data-scroll-to-blockanddata-scroll-to-inlineignore unknown values (a typo such as"centre") and keep the option or default alignment, instead of falling back tonearest.
Changed
- Internal: the DOM controller moved from
src/coretosrc/vanilla;src/corekeeps the DOM-free types, constants and helpers. Public entries are unchanged. - The package moved from the
samline/utilsmonorepo to its own repository, samline/scroll-to. Homepage, repository and documentation links point to the package’s own site.
[1.0.0] - 2026-11-13
Added
- First release:
scrollToanimates the page or any container to an element,#id, selector,'top'or position, withoffset(pixels, percentages or a live element such as a fixed header),blockandinlinealignment,durationandeasing, a destination measured on every frame, interruption by the visitor, reduced motion, focus and URL hash handling, and a promise that tells whether it arrived.scrollPositionmeasures without moving,cancelScrollstops a scroll, andautoScrollTohandles same-page links and[data-scroll-to]triggers with one delegated listener, aligning the URL hash on load. ESM, CommonJS and a browser global (window.ScrollTo) that starts on its own.