- Docs
- Getting started
Getting started
Install @samline/horizontal-scroll with a package manager or a script tag and pin your first horizontally scrolling section.
Install @samline/horizontal-scroll, then follow the Package / ESM or the HTML / CDN path to the first section. Both use the same API.
Requirements
- Any modern browser with
position: sticky. Without JavaScript the row keeps your CSS. - On the server,
horizontalScrollreturns an inert object andautoHorizontalScrolldoes nothing. - No runtime dependencies.
Install
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>Package / ESM
import { autoHorizontalScroll } from '@samline/horizontal-scroll'
autoHorizontalScroll()
<section data-horizontal-scroll aria-label="Gallery">
<div data-horizontal-scroll-track class="row">
<article class="card">…</article>
<article class="card">…</article>
<article class="card">…</article>
</div>
</section>
/* The fallback: a native horizontal scroll. */
[data-horizontal-scroll] {
overflow-x: auto;
}
.row {
display: flex;
gap: 1.5rem;
height: 100vh;
align-items: center;
}
.card {
flex: 0 0 min(70vw, 28rem);
}
autoHorizontalScroll() sets up every [data-horizontal-scroll] in the page, including sections added later. To set up one section, call horizontalScroll(section, options); it returns { active, progress, refresh, destroy }. Available as ESM and CommonJS (require('@samline/horizontal-scroll')). There is no stylesheet.
The track is the [data-horizontal-scroll-track] element, or the section’s first child. It must be wider than the section: either its children overflow it (a flex row), or it is wider itself (width: max-content).
HTML / CDN
For Shopify, WordPress or plain HTML pages without a build step, load the browser bundle. It sets up every [data-horizontal-scroll] as soon as the DOM is ready. Pin the version in production.
<script
src="https://cdn.jsdelivr.net/npm/@samline/horizontal-scroll@1.0.1/dist/browser/horizontal-scroll.global.js"
defer
></script>
To pass options, add data-manual to the script tag and start it yourself, or call HorizontalScroll.auto() from a script that runs before the DOM is ready (a deferred or inline script after the bundle):
<script
src="https://cdn.jsdelivr.net/npm/@samline/horizontal-scroll@1.0.1/dist/browser/horizontal-scroll.global.js"
data-manual
defer
></script>
<script type="module">
HorizontalScroll.auto({ top: 64, media: '(min-width: 48rem)' })
</script>
Working starter files
A complete page you can save and open: the live preview runs the real package, and its files load the published browser bundle.
The section pins to the top while its row of cards crosses the screen, then the page carries on. Tab through the cards: the page follows the focus.
Scroll down
The end
Explore the code
HTML / CDN
HTML
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Scroll down, move sideways</title>
<link rel="stylesheet" href="./style.css" />
</head>
<body>
<main>
<p class="spacer">Scroll down</p>
<section data-horizontal-scroll aria-label="Gallery">
<div data-horizontal-scroll-track class="track">
<article class="card" tabindex="0">Card 1</article>
<article class="card" tabindex="0">Card 2</article>
<article class="card" tabindex="0">Card 3</article>
<article class="card" tabindex="0">Card 4</article>
<article class="card" tabindex="0">Card 5</article>
<article class="card" tabindex="0">Card 6</article>
</div>
</section>
<p class="spacer">The end</p>
</main>
<script src="https://cdn.jsdelivr.net/npm/@samline/horizontal-scroll@1.0.1/dist/browser/horizontal-scroll.global.js"></script>
<script src="./main.js" defer></script>
</body>
</html>
CSS
/* Without JavaScript, or when it is off, the row scrolls natively. */
[data-horizontal-scroll] {
overflow-x: auto;
}
body {
margin: 0;
font-family: system-ui, sans-serif;
}
.spacer {
height: 80vh;
display: grid;
place-items: center;
margin: 0;
}
.track {
display: flex;
gap: 1.5rem;
height: 100vh;
align-items: center;
padding: 0 1.5rem;
box-sizing: border-box;
}
.card {
flex: 0 0 min(70vw, 28rem);
height: 60vh;
display: grid;
place-items: center;
border-radius: 1rem;
background: #efeafd;
font-size: 1.5rem;
}
.card:focus-visible {
outline: 3px solid #0f766e;
outline-offset: 4px;
}
JavaScript
// Nothing to call: the script sets up every [data-horizontal-scroll] on its own.
Complete file
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Scroll down, move sideways</title>
<style>
/* Without JavaScript, or when it is off, the row scrolls natively. */
[data-horizontal-scroll] {
overflow-x: auto;
}
body {
margin: 0;
font-family: system-ui, sans-serif;
}
.spacer {
height: 80vh;
display: grid;
place-items: center;
margin: 0;
}
.track {
display: flex;
gap: 1.5rem;
height: 100vh;
align-items: center;
padding: 0 1.5rem;
box-sizing: border-box;
}
.card {
flex: 0 0 min(70vw, 28rem);
height: 60vh;
display: grid;
place-items: center;
border-radius: 1rem;
background: #efeafd;
font-size: 1.5rem;
}
.card:focus-visible {
outline: 3px solid #0f766e;
outline-offset: 4px;
}
</style>
</head>
<body>
<main>
<p class="spacer">Scroll down</p>
<section data-horizontal-scroll aria-label="Gallery">
<div data-horizontal-scroll-track class="track">
<article class="card" tabindex="0">Card 1</article>
<article class="card" tabindex="0">Card 2</article>
<article class="card" tabindex="0">Card 3</article>
<article class="card" tabindex="0">Card 4</article>
<article class="card" tabindex="0">Card 5</article>
<article class="card" tabindex="0">Card 6</article>
</div>
</section>
<p class="spacer">The end</p>
</main>
<script src="https://cdn.jsdelivr.net/npm/@samline/horizontal-scroll@1.0.1/dist/browser/horizontal-scroll.global.js"></script>
<script>
// Nothing to call: the script sets up every [data-horizontal-scroll] on its own.
</script>
</body>
</html>
Package / ESM
HTML
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Scroll down, move sideways</title>
<link rel="stylesheet" href="./style.css" />
</head>
<body>
<main>
<p class="spacer">Scroll down</p>
<section data-horizontal-scroll aria-label="Gallery">
<div data-horizontal-scroll-track class="track">
<article class="card" tabindex="0">Card 1</article>
<article class="card" tabindex="0">Card 2</article>
<article class="card" tabindex="0">Card 3</article>
<article class="card" tabindex="0">Card 4</article>
<article class="card" tabindex="0">Card 5</article>
<article class="card" tabindex="0">Card 6</article>
</div>
</section>
<p class="spacer">The end</p>
</main>
<script type="module" src="./main.js"></script>
</body>
</html>
CSS
/* Without JavaScript, or when it is off, the row scrolls natively. */
[data-horizontal-scroll] {
overflow-x: auto;
}
body {
margin: 0;
font-family: system-ui, sans-serif;
}
.spacer {
height: 80vh;
display: grid;
place-items: center;
margin: 0;
}
.track {
display: flex;
gap: 1.5rem;
height: 100vh;
align-items: center;
padding: 0 1.5rem;
box-sizing: border-box;
}
.card {
flex: 0 0 min(70vw, 28rem);
height: 60vh;
display: grid;
place-items: center;
border-radius: 1rem;
background: #efeafd;
font-size: 1.5rem;
}
.card:focus-visible {
outline: 3px solid #0f766e;
outline-offset: 4px;
}
JavaScript
import { autoHorizontalScroll } from '@samline/horizontal-scroll'
autoHorizontalScroll()
Complete file
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Scroll down, move sideways</title>
<style>
/* Without JavaScript, or when it is off, the row scrolls natively. */
[data-horizontal-scroll] {
overflow-x: auto;
}
body {
margin: 0;
font-family: system-ui, sans-serif;
}
.spacer {
height: 80vh;
display: grid;
place-items: center;
margin: 0;
}
.track {
display: flex;
gap: 1.5rem;
height: 100vh;
align-items: center;
padding: 0 1.5rem;
box-sizing: border-box;
}
.card {
flex: 0 0 min(70vw, 28rem);
height: 60vh;
display: grid;
place-items: center;
border-radius: 1rem;
background: #efeafd;
font-size: 1.5rem;
}
.card:focus-visible {
outline: 3px solid #0f766e;
outline-offset: 4px;
}
</style>
</head>
<body>
<main>
<p class="spacer">Scroll down</p>
<section data-horizontal-scroll aria-label="Gallery">
<div data-horizontal-scroll-track class="track">
<article class="card" tabindex="0">Card 1</article>
<article class="card" tabindex="0">Card 2</article>
<article class="card" tabindex="0">Card 3</article>
<article class="card" tabindex="0">Card 4</article>
<article class="card" tabindex="0">Card 5</article>
<article class="card" tabindex="0">Card 6</article>
</div>
</section>
<p class="spacer">The end</p>
</main>
<script type="module">
import { autoHorizontalScroll } from '@samline/horizontal-scroll'
autoHorizontalScroll()
</script>
</body>
</html>
Next steps
Live previews with the complete, copyable source of each one.
API referenceSignatures and behavior of horizontalScroll, autoHorizontalScroll and window.HorizontalScroll.
Attributes and options.
Layouts and fallbacksHeaders, fallbacks, focus, scroll containers and sticky pitfalls.
Accessibility and motionFocus, reduced motion and what your page provides.
Framework integrationsReact, Vue, Svelte, Astro and page swaps.