Horizontal Scroll
A row that crosses the screen as you scroll.
Add data-horizontal-scroll to a section and its row pins to the top while the page scroll moves it sideways, then lets the page carry on.
Install it, scroll the live preview, then read the full reference.
npm install @samline/horizontal-scrollAbout 2.5 KB gzipZero dependenciesMIT licensed
Scroll this box
The page carries on
ONE SMALL SCRIPT. RIGHT AT HOME IN YOUR STACK.
The scroll you expect.
The details you forget.
Sized for you
The section grows exactly tall enough to cross its row, and measures again when images, fonts or the window change.
Keyboard friendly
Tab to a card that is off to the side and the page scrolls until it is in view, so focus never disappears.
A real fallback
Without JavaScript, outside your media query or with reduced motion, the row is left to your CSS, such as a native swipe.
No scroll hijacking
The page keeps its own scrolling: wheel, touch, keys and scrollbars all work. Only the row position follows it.
Smooth on every frame
One read per frame and a GPU-friendly translate, with sticky positioning doing the pinning instead of JavaScript.
Progress for free
A --horizontal-scroll-progress variable and an onProgress callback drive bars, counters and effects.
A row first. Motion when it fits.
Your content stays a plain row that scrolls natively without JavaScript.
Package
@samline/horizontal-scroll
horizontalScroll and autoHorizontalScroll as ESM or CommonJS.
One section
horizontalScroll(section, options)
Returns { active, progress, refresh, destroy }.
Whole page
autoHorizontalScroll(options)
Every [data-horizontal-scroll], including sections added later.
HTML / CDN
window.HorizontalScroll
A classic script that starts on its own.
Progress
onProgress({ progress, x })
From 0 to 1, for bars, counters and analytics.
Styling
[data-horizontal-scroll-state]
No stylesheet: style the active and fallback states your way.
One attribute. One call.
Turn a row of cards into a pinned horizontal section.
Read the installation guideInstall
npm
npm install @samline/horizontal-scrollpnpm
pnpm add @samline/horizontal-scrollyarn
yarn add @samline/horizontal-scrollbun
bun add @samline/horizontal-scrollHTML / CDN
<script src="https://cdn.jsdelivr.net/npm/@samline/horizontal-scroll@1.0.1/dist/browser/horizontal-scroll.global.js" defer></script>Mark the section
A section with data-horizontal-scroll around a row (the track) that is wider than the screen.
<section data-horizontal-scroll>
<div data-horizontal-scroll-track class="row">
<article>…</article>
<article>…</article>
<article>…</article>
</div>
</section>Start it
import { autoHorizontalScroll } from '@samline/horizontal-scroll'
autoHorizontalScroll()Continue with every option, the fallback and scroll containers.
Explore the optionsPlain markup.
Precise motion.
Three common jobs, without measuring a single card yourself.
<section data-horizontal-scroll data-horizontal-scroll-top="64">…</section><section
data-horizontal-scroll
data-horizontal-scroll-media="(min-width: 48rem)"
>…</section>.progress {
transform-origin: left;
transform: scaleX(var(--horizontal-scroll-progress, 0));
}A few details. Clearly answered.
How does it work?
Does it work without a bundler?
Can it run only on wide screens?
The row is not pinning. Why?
What about reduced motion?
Can I change the speed?
What happens without JavaScript?
Does it see content added later?
Let the page scroll, and the row travel.
Try the examples or follow the first steps.
Guides, the complete API and release notes, in one place.
Read the documentation