- Docs
- Lifecycle and events
Lifecycle and events
Follow a scroll with onStart, onProgress and onEnd, read why it ended, use events, the state attribute, AbortSignal and createScrollTo.
Every scroll goes through the same steps: it starts, moves frame by frame, and ends exactly once. You can follow those steps three ways. Use whichever fits the code you have:
| Way | Where it fits |
|---|---|
| Callbacks | Code that starts the scroll itself |
scroll-to:* events |
Code that only listens, such as analytics or a widget |
data-scroll-to-state |
CSS, with no JavaScript of your own |
Callbacks
Pass onStart, onProgress and onEnd to scrollTo, autoScrollTo or createScrollTo:
import { scrollTo } from '@samline/scroll-to'
scrollTo('#pricing', {
offset: '#header',
onStart: ({ target, top }) => console.log('leaving', top, 'for', target),
onProgress: ({ progress, eased, top }) => console.log(progress, eased, top),
onEnd: ({ arrived, reason, top }) => console.log(arrived, reason, top),
})
| Callback | When | Receives |
|---|---|---|
onStart |
Once, before the first frame | { target, container, trigger, top, left } |
onProgress |
On every animation frame | The same, plus progress and eased, both from 0 to 1 |
onEnd |
Once, when the scroll ends for any reason | The same as onStart, plus arrived and reason |
targetis the element scrolled to, ornullfor positions and'top'.containeriswindowfor the page, or the scrolling element.triggeris the link or[data-scroll-to]element that was clicked whenautoScrollTostarted the scroll, andnullotherwise.topandleftare where the container is at that moment, in pixels.progressis the time elapsed.easedis the distance covered, after easing. A progress bar that follows the page useseased.
A jump (behavior: 'instant', reduced motion, or a target already in place) still calls all three: onStart, a single onProgress with progress: 1, then onEnd.
When onEnd runs, focus and the URL hash have already changed, and the state attribute is already gone.
Why it ended
onEnd and the scroll-to:end event say why the scroll ended. arrived is true only when reason is 'arrived', and it matches what the promise resolves to.
reason |
What happened |
|---|---|
'arrived' |
It reached the target |
'interrupted' |
The visitor took over: the wheel, a touch, a key that scrolls, or a press on the scrollbar |
'replaced' |
Another scroll started on the same container |
'cancelled' |
cancelScroll(), an aborted signal, or destroy() on a createScrollTo instance |
'missing' |
The target does not exist (onStart is not called) |
Treat them differently when it matters. For example, highlight only on arrival, and do nothing if the visitor took over:
scrollTo('#faq-4', {
onEnd: ({ reason, target }) => {
if (reason === 'arrived') target.classList.add('flash')
if (reason === 'missing') console.warn('No #faq-4 on this page')
},
})
END_REASONS lists the five values, for validation or for TypeScript (ScrollEndReason).
Events
Every scroll dispatches two bubbling CustomEvents, with the same details as the callbacks in event.detail:
| Event | Detail |
|---|---|
scroll-to:start |
Same as onStart |
scroll-to:end |
Same as onEnd, with reason |
They are dispatched on the target element. For positions, 'top' and missing targets, they are dispatched on the scrolling element: document.documentElement for the page, or the container. Because they bubble, one listener on document hears every scroll on the page, including the ones the CDN script starts on its own:
document.addEventListener('scroll-to:end', event => {
const { reason, target, trigger } = event.detail
if (reason !== 'arrived' || !target?.id) return
analytics.track('section_reached', { id: target.id, from: trigger?.textContent })
})
Listen on one section to react only to scrolls that go there:
document.querySelector('#signup').addEventListener('scroll-to:end', event => {
if (event.detail.arrived) document.querySelector('#email').focus()
})
EVENTS holds the names: EVENTS.start is 'scroll-to:start' and EVENTS.end is 'scroll-to:end'.
The state attribute
While a scroll runs, data-scroll-to-state="scrolling" is set on the scrolling element (<html> for the page, or the container) and, when autoScrollTo started it, on the trigger that was clicked. It is removed when the scroll ends, whatever the reason.
Use it from CSS. For example, keep a header that hides on scroll down visible during a scripted scroll, and show which link is on its way:
html[data-scroll-to-state='scrolling'] .header {
transform: none;
}
a[data-scroll-to-state='scrolling'] {
opacity: 0.6;
}
From JavaScript, ask with isScrolling(container?):
import { isScrolling } from '@samline/scroll-to'
window.addEventListener('scroll', () => {
if (isScrolling()) return // our own scroll, not the visitor's
hideHeaderOnScrollDown()
})
Stop it with an AbortSignal
Pass a signal to stop the scroll from anywhere. The promise resolves to false and reason is 'cancelled'. A signal that is already aborted does not start a scroll and leaves the running one alone.
const controller = new AbortController()
scrollTo('#results', { signal: controller.signal })
// Later: a new search started, the modal closed, the route changed…
controller.abort()
One signal can stop several scrolls, and it works with AbortSignal.timeout(ms):
// Give up after 2 seconds, wherever it is.
scrollTo('#footer', { duration: 5000, signal: AbortSignal.timeout(2000) })
cancelScroll(container?) does the same for whatever is running on a container, without a signal.
The wheel, a touch, a key that scrolls or a press on the scrollbar interrupts a scroll on its own (reason: 'interrupted'), unless you pass interruptible: false. Clicks on buttons and links do not, so a “Stop” button calls cancelScroll() or abort() and the scroll ends as 'cancelled'. Use signal for stops that do not come from the visitor too: a timeout, a new request, a route change or a component that unmounts.
Share defaults with createScrollTo
When every scroll on a page uses the same options, write them once:
import { createScrollTo } from '@samline/scroll-to'
const scroller = createScrollTo({ offset: '#header', duration: 600, easing: 'ease-out' })
scroller.auto() // same-page links and [data-scroll-to], with the defaults
await scroller.to('#pricing') // a scroll from code, with the defaults
scroller.position('#faq') // { top, left }, without moving
| Member | Does |
|---|---|
to(target, options?) |
scrollTo with the defaults |
position(target, options?) |
scrollPosition with the defaults |
cancel() |
Stop the scroll running on the default container |
isScrolling() |
Whether the default container is scrolling |
auto(options?) |
autoScrollTo with the defaults; returns its own { destroy } |
destroy() |
Stop the scrolls this instance started and every auto() controller |
Options passed to a call replace the defaults key by key, callbacks included:
scroller.to('#top-banner', { offset: 0 }) // no header offset for this one
destroy() is safe to call more than once. It stops only the scrolls this instance started, never another script’s, and afterwards to() resolves to false, position() returns null and auto() does nothing. That makes one instance per component or page easy to clean up:
// A scroll box in a component.
const panel = createScrollTo({ container: '#panel', block: 'nearest' })
panel.auto({ scope: document.querySelector('#panel-nav') })
// On unmount:
panel.destroy()
In the browser global
The CDN script exposes the same API on window.ScrollTo: ScrollTo.isScrolling(), ScrollTo.createScrollTo(defaults), and every callback and signal option. Events work with no extra code, since the automatic start dispatches them too.
<script
src="https://cdn.jsdelivr.net/npm/@samline/scroll-to@1.6.0/dist/browser/scroll-to.global.js"
defer
></script>
<script>
document.addEventListener('scroll-to:end', event => {
if (event.detail.arrived) event.detail.target?.classList.add('flash')
})
</script>
Without a DOM
On the server every function stays inert: scrollTo resolves to false without calling any callback, isScrolling() returns false, and a createScrollTo instance does nothing.