Scroll down, travel sideways.

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-scroll

About 2.5 KB gzipZero dependenciesMIT licensed

Horizontal Scroll previewLive preview

Scroll this box

01PinThe row sticks to the top of the box.
02SlideScrolling down moves it sideways.
03MeasureThe section grows to fit the row.
04FocusTab to a card and the box follows.
05Fall backReduced motion gets a native scroll.
06ReleaseAt the end, the page carries on.

The page carries on

0% across

ONE SMALL SCRIPT. RIGHT AT HOME IN YOUR STACK.

JavaScript TypeScript React Vue Svelte Shopify WordPress
01 / More than a sticky row

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.

02 / Fit it into your stack

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.

03 / Install and pin

One attribute. One call.

Turn a row of cards into a pinned horizontal section.

Read the installation guide
1

Install

npm

Terminal
npm install @samline/horizontal-scroll

pnpm

Terminal
pnpm add @samline/horizontal-scroll

yarn

Terminal
yarn add @samline/horizontal-scroll

bun

Terminal
bun add @samline/horizontal-scroll

HTML / CDN

Terminal
<script src="https://cdn.jsdelivr.net/npm/@samline/horizontal-scroll@1.0.1/dist/browser/horizontal-scroll.global.js" defer></script>
2

Mark the section

A section with data-horizontal-scroll around a row (the track) that is wider than the screen.

index.html
<section data-horizontal-scroll>
  <div data-horizontal-scroll-track class="row">
    <article>…</article>
    <article>…</article>
    <article>…</article>
  </div>
</section>
3

Start it

main.js
import { autoHorizontalScroll } from '@samline/horizontal-scroll'

autoHorizontalScroll()
Copy complete working files

Continue with every option, the fallback and scroll containers.

Explore the options
04 / Beyond a gallery

Plain markup.
Precise motion.

Three common jobs, without measuring a single card yourself.

top

Below a fixed header

Pin the row under your header.

Read the options
index.html
<section data-horizontal-scroll data-horizontal-scroll-top="64">…</section>
media

Only on wide screens

Keep a native swipe on phones.

Read the options
index.html
<section
  data-horizontal-scroll
  data-horizontal-scroll-media="(min-width: 48rem)"
>…</section>
--horizontal-scroll-progress

A progress bar

Show how far along the row is, in CSS.

Read the API
style.css
.progress {
  transform-origin: left;
  transform: scaleX(var(--horizontal-scroll-progress, 0));
}
Explore working examples
05 / Before you build

A few details. Clearly answered.

How does it work?
The section gets a height of the row plus its overflow, the row becomes position: sticky, and on every scroll frame its translate follows how far the section has been scrolled.
Does it work without a bundler?
Yes. Load dist/browser/horizontal-scroll.global.js; it sets up every [data-horizontal-scroll] on its own. Add data-manual to the script tag to start it yourself with HorizontalScroll.auto(). Pin the version in production.
Can it run only on wide screens?
Yes. Set media, or data-horizontal-scroll-media, to a query such as (min-width: 48rem). It is followed live: outside it the section is released and the row is left to your CSS, such as a native swipe.
The row is not pinning. Why?
An ancestor with overflow: hidden or auto stops position: sticky. Use overflow: clip there, or pass that ancestor as root when it is the element that scrolls.
What about reduced motion?
By default the effect turns off when the visitor prefers reduced motion, and the row falls back to your CSS. Set respectReducedMotion: false to keep it.
Can I change the speed?
speed sets how many horizontal pixels move per vertical pixel scrolled. 2 crosses the row in half the scrolling; 0.5 takes twice as long.
What happens without JavaScript?
Nothing is pinned or resized. Add overflow-x: auto to the section in your CSS and the row scrolls sideways natively.
Does it see content added later?
autoHorizontalScroll and the CDN script set up new sections. Size changes inside a row are measured on their own; after replacing the track, call refresh().
Sideways, on your terms

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