Reference

Configuration options

Every @samline/scroll-to option, callback and data-scroll-to attribute, with defaults, the state attribute and the events.

Options

scrollTo, scrollPosition and autoScrollTo take the same options.

Option Default Description
container the page What scrolls: an element or a selector. Use it for boxes, tab strips and carousels. 'auto' scrolls every box around the target, then the page, like scrollIntoView; the offset applies to the outermost one
offset 0 Space kept above the target: pixels (80 or '80px'), a percentage of the container height ('10%'), an element or selector whose height is used ('#header'), 'auto' (fixed and sticky elements stuck at the top), 'css' (scroll-padding-top plus scroll-margin-top), a function ({ container, target }) => number, or an array of these, added up
block 'start' Vertical alignment: start, center, end or nearest (only scrolls when the target is not fully visible)
inline 'nearest' Horizontal alignment, same values
duration 'auto' Milliseconds, or 'auto': half a millisecond per pixel, from 300 to 1000, or from speed
speed none Pixels per second for an 'auto' duration
maxDuration 1000 (none with speed) The longest an 'auto' duration can last, in milliseconds
easing 'ease-in-out' 'ease-in-out', 'ease-out', 'ease-out-quint', 'ease-in', 'ease-out-back', 'linear', a 'cubic-bezier(x1, y1, x2, y2)' string or a function from 0–1 to 0–1
sections 'section' What 'next' and 'prev' step through, inside the container
reveal true Open closed <details> and hidden="until-found" content around the target before scrolling
when 'always' 'needed' does not move when the target element is already fully visible below the offset
behavior 'smooth' 'instant' jumps. Reduced motion always jumps.
queue false Wait for the running scroll on the container, and the ones already waiting, instead of replacing it. A scroll without queue, an interruption or cancelScroll() ends the waiting ones unstarted
interruptible true Stop when the visitor takes over: the wheel, a touch, a key that scrolls, or a mouse press outside links and buttons
highlight false Mark the target with data-scroll-to-arrived on arrival, for a CSS highlight: true for 1500 ms, or milliseconds
focus false (true for autoScrollTo) Move keyboard focus to the target on arrival. Targets that cannot take focus get tabindex="-1".
hash false ('push' for autoScrollTo) Write the target’s #id to the URL on arrival: 'push' adds a history entry, 'replace' does not
signal none An AbortSignal. Aborting it stops the scroll (reason: 'cancelled'); an aborted signal does not start one
onStart none (detail) => void, once before the first frame, with { target, container, trigger, top, left }
onProgress none (detail) => void, on every frame, with the same plus progress (time) and eased (distance), from 0 to 1
onEnd none (result) => void, once when it ends, with the same plus arrived and reason: arrived, interrupted, replaced, cancelled or missing

autoScrollTo also takes:

Option Default Description
selector '[data-scroll-to], a[href^="#"]' Triggers to handle. Use '[data-scroll-to]' to leave plain links alone, or add 'a[href*="#"]' for full URLs to this page.
scope document Where clicks are listened to
initialHash true With an offset, align the URL’s #id once the page loads, since the browser’s own jump ignores the offset

Targets

Value Scrolls to
An element That element
'#pricing' The element with that id (ids with special characters work)
A selector The first match
'top', '#top' or '#' The top
'bottom' The bottom
'next', 'prev' The next or previous of sections from where it is now
A number That vertical position, in pixels
'+=400', '-=50%' Relative to where it is now; % of the container height
{ top, left } A point; each axis takes a number or a relative string, and % on left is of the width

Attributes

Set them on a trigger. They win over the options given to autoScrollTo.

Attribute Value Description
data-scroll-to target The target. Empty on a link: its href is used.
data-scroll-to-offset pixels, %, a selector, auto or css offset
data-scroll-to-container selector or auto container
data-scroll-to-block start, center, end, nearest block
data-scroll-to-inline start, center, end, nearest inline
data-scroll-to-duration milliseconds duration
data-scroll-to-speed pixels per second speed
data-scroll-to-easing a name or cubic-bezier(…) easing
data-scroll-to-when always, needed when
data-scroll-to-sections selector sections
data-scroll-to-focus true, false focus
data-scroll-to-hash push, replace, false hash
data-scroll-to-reveal true, false reveal
data-scroll-to-queue true, false queue
data-scroll-to-highlight true, false or milliseconds highlight

With the browser bundle, data-scroll-to-back-to-top on any element makes it a back-to-top button; its value is the threshold, in pixels or %, and empty for one screen.

State and events

Name Where When
data-scroll-to-state="scrolling" The scrolling element (<html> for the page) and the clicked trigger While the scroll runs
--scroll-to-progress The same elements, as an inline custom property from 0 to 1 While the scroll runs
data-scroll-to-arrived The target For highlight ms after it arrives
data-scroll-to-visible A backToTop button: 'true' or 'false' Once it runs
--scroll-to-scrolled A backToTop button, from 0 at the top to 1 at the end Once it runs
scroll-to:start The target, or the scrolling element for positions When it starts
scroll-to:end The target, or the scrolling element for positions and missing targets When it ends, once

The events bubble and carry the same details as the callbacks. Lifecycle and events shows how to use them.

While it runs

  • scroll-snap-type is turned off on every container that moves, with an inline none !important, and restored when the scroll ends.
  • Each frame is set with behavior: 'instant', so CSS scroll-behavior: smooth does not add its own glide.
  • In right-to-left containers, inline: 'start' is the right edge, 'next' steps to the left, and horizontal positions are 0 at the right and negative to the left, as scrollLeft reads.

Clicks

Clicks with a modifier key or a middle button, and clicks whose default another script already prevented, are left alone. Links to other pages and to ids that do not exist keep their normal behavior.