- Docs
- API reference
API reference
Every @samline/horizontal-scroll export, horizontalScroll, autoHorizontalScroll, their types and the window.HorizontalScroll global.
horizontalScroll(section, options?)
horizontalScroll(section: Element | string, options?: HorizontalScrollOptions): HorizontalScroll
Pins section (an element or a selector) and moves its track sideways with the scroll. See Options for every option.
import { horizontalScroll } from '@samline/horizontal-scroll'
const scroller = horizontalScroll('#gallery', {
top: 64,
onProgress: ({ progress }) => console.log(Math.round(progress * 100) + '%'),
})
It returns:
| Member | Description |
|---|---|
active |
true while the section is pinned (read-only) |
progress |
From 0 to 1 (read-only) |
refresh() |
Measure again, and pick up a replaced track. Size changes inside the track and window resizes are handled on their own. |
destroy() |
Stop, restore the styles it changed and remove the state attribute |
Without a DOM, or when the section is not found, it returns an inert object.
autoHorizontalScroll(options?)
autoHorizontalScroll(options?: AutoHorizontalScrollOptions): { refresh(): void; destroy(): void }
Calls horizontalScroll for every [data-horizontal-scroll] in scope (default document) with the same options, sets up sections added later and cleans up sections that are removed. Pass observe: false to skip watching for changes, and selector to match other sections.
onProgress
interface HorizontalScrollProgress {
progress: number // 0 to 1
x: number // current translate, 0 or negative
distance: number // total travel in pixels
}
Called whenever the progress changes, and with progress: 0 when the effect turns off. The same value is on the section as the CSS variable --horizontal-scroll-progress, which the track and its children inherit:
.progress {
transform-origin: left;
transform: scaleX(var(--horizontal-scroll-progress, 0));
}
Constants
| Export | Value |
|---|---|
ATTRIBUTE |
'data-horizontal-scroll' |
TRACK_ATTRIBUTE |
'data-horizontal-scroll-track' |
STATE_ATTRIBUTE |
'data-horizontal-scroll-state' |
PROGRESS_PROPERTY |
'--horizontal-scroll-progress' |
Types: HorizontalScroll, HorizontalScrollOptions, HorizontalScrollProgress, AutoHorizontalScrollOptions, AutoInitController and ElementTarget. The default export is horizontalScroll; @samline/horizontal-scroll/vanilla exports the same API.
window.HorizontalScroll
The browser bundle (dist/browser/horizontal-scroll.global.js) defines:
| Member | Description |
|---|---|
HorizontalScroll.horizontalScroll |
Same as the package export |
HorizontalScroll.autoHorizontalScroll |
Same as the package export |
HorizontalScroll.auto(options?) |
Start (or restart) the automatic setup with options; returns the controller |
HorizontalScroll.controller |
The controller of the automatic run, or null |
It starts on its own when the DOM is ready. With data-manual on the script tag it waits for HorizontalScroll.auto(); a call made before the DOM is ready also replaces the automatic start.