Guide

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, horizontalScroll returns an inert object and autoHorizontalScroll does nothing.
  • No runtime dependencies.

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>

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.

Pinned galleryLive preview

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

Card 1
Card 2
Card 3
Card 4
Card 5
Card 6

The end

Explore the code

HTML / CDN

HTML

index.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

style.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

main.js
// Nothing to call: the script sets up every [data-horizontal-scroll] on its own.

Complete file

index.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>
    <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

index.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

style.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

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

autoHorizontalScroll()

Complete file

index.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>
    <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