Guide

Queues and guided tours

Queue scrolls one after another with queue, and build guided tours, demos and kiosks with scrollSequence: play, pause, next, prev and loop.

One after another

A new scroll on a container replaces the running one: the first ends with reason: 'replaced' and the new one starts from wherever the first had reached. With queue: true, the new scroll waits instead, and starts once the running one ends:

import { scrollTo } from '@samline/scroll-to'

scrollTo('#intro')
scrollTo('#features', { queue: true })
scrollTo('#pricing', { queue: true }) // waits for both

Each queued scroll keeps its own options and its own promise, which resolves when it ends. On a trigger, add data-scroll-to-queue:

<button type="button" data-scroll-to="next" data-scroll-to-queue>Next section</button>

When the line is cleared

The waiting scrolls never start, and end without moving, when:

What happens They end with
A scroll without queue starts 'replaced'
The visitor takes over the running scroll 'interrupted'
cancelScroll(), or the running scroll’s signal aborts 'cancelled'

Their promises resolve to false, and onEnd and scroll-to:end report the reason as usual. A running scroll that arrives, or whose target is missing, lets the next one start.

Queues are kept per container. With container: 'auto', a queued scroll waits for the page’s scroll.

Guided tours

scrollSequence walks through a list of stops, for product tours, demos, presentations and kiosks. It comes from its own entry, so pages that do not use it do not load it:

import { scrollSequence } from '@samline/scroll-to/sequence'

const tour = scrollSequence(
  ['#welcome', '#search', { target: '#reports', pause: 4000 }, '#share'],
  {
    offset: '#header',
    pause: 2000,
  }
)

play.addEventListener('click', () => tour.toggle())
next.addEventListener('click', () => tour.next())
prev.addEventListener('click', () => tour.prev())

With the browser bundle it is ScrollTo.scrollSequence.

Steps

Each step is a target (anything scrollTo takes) or an object with a target, its own pause, and any scroll option, which wins over the sequence’s options for that step:

scrollSequence([
  '#intro',
  { target: '#chart', block: 'center', pause: 5000 },
  { target: '#table', duration: 1200, highlight: true },
])

Playing

Method What it does
play() Moves on by itself from the next step, staying pause ms on each. From the end, it starts over.
pause() Stops moving on. A scroll on its way still arrives.
toggle() play() or pause()
next() Scrolls to the next step. Resolves true on arrival, false past the last step without loop.
prev() Scrolls to the previous step
goTo(i) Scrolls to step i, clamped to the list
destroy() Stops playing and stops its scroll ('cancelled'). Idempotent; later calls do nothing.

index (-1 before the first step), playing and length read where it is. Stepping by hand while it plays keeps it playing: the pause starts again from the step you chose.

Option Default Description
pause 2000 How long each step stays while playing, in milliseconds
loop false After the last step, start again from the first
autoplay false Start playing at once
onChange none ({ index, playing, step }) => void, when either changes

Every other option is a scroll option for every step: offset, container, duration, easing, highlight and the rest.

The visitor stays in control

A tour pauses on its own when the visitor scrolls, touches the page or presses a key that scrolls ('interrupted'), and when another scroll replaces its own, such as a click on a link ('replaced'). It does not move focus unless a step asks for focus: true.

Content that moves by itself for more than five seconds needs a way to pause it (WCAG 2.2.2). Always show a Pause button next to a playing tour, and keep its label in sync with onChange:

const tour = scrollSequence(stops, {
  onChange: ({ index, playing }) => {
    play.textContent = playing ? 'Pause' : 'Play'
    play.setAttribute('aria-pressed', String(playing))
    status.textContent = `Stop ${index + 1} of ${tour.length}`
  },
})

Put the counter in an aria-live="polite" region so screen readers hear where the tour is. With reduced motion every step jumps instead of scrolling, and the tour keeps its timing.