Skip to content
@samline/horizontal-scrollv1.0.1
AboutInstallRecipesFAQExamplesDocs

@samline/horizontal-scroll

Explore Horizontal Scroll

A starting point, a working example, and the details when you need them.

  • 01AboutUnderstand the problem and the approach.
  • 02InstallChoose your setup and follow the first steps.
  • 03RecipesUseful patterns and integration context.
  • 04FAQFind the practical details.
  • 05ExamplesTry a preview and explore its code.
  • 06DocsRead guides and the complete reference.

Around the project

  • GitHub(opens in a new tab)
  • npm(opens in a new tab)

v1.0.1·MIT

GitHub(opens in a new tab)Get started
Examples

Horizontal Scroll examples.

Live previews of distinct scenarios, each with independently copyable files. The same examples appear in the documentation.

Try the exampleInstallation guide

Each preview runs the real package. The copied files load the published browser bundle, so they run as they are.

Choose an example

Pinned galleryProgress barWide screens only
01 / Pinned gallery

Scroll down, move sideways

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>
02 / Progress bar

Under a fixed header, with progress

Progress barLive preview

top keeps the pinned row below a 64px header, speed crosses it in less scrolling, and the --horizontal-scroll-progress variable drives a bar in CSS.

Timeline

Scroll down

  1. 2017
  2. 2018
  3. 2019
  4. 2020
  5. 2021
  6. 2022
  7. 2023
  8. 2024

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>Under a fixed header, with progress</title>
    <link rel="stylesheet" href="./style.css" />
  </head>
  <body>
    <main>
      <header class="bar-header">Timeline<span class="progress"></span></header>
      <p class="spacer">Scroll down</p>
      <section data-horizontal-scroll aria-label="Timeline">
        <ol data-horizontal-scroll-track class="track">
          <li class="step" tabindex="0">2017</li>
          <li class="step" tabindex="0">2018</li>
          <li class="step" tabindex="0">2019</li>
          <li class="step" tabindex="0">2020</li>
          <li class="step" tabindex="0">2021</li>
          <li class="step" tabindex="0">2022</li>
          <li class="step" tabindex="0">2023</li>
          <li class="step" tabindex="0">2024</li>
        </ol>
      </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;
}
.bar-header {
  position: fixed;
  inset: 0 0 auto;
  z-index: 1;
  height: 64px;
  display: flex;
  align-items: center;
  padding: 0 1.5rem;
  background: #fff;
  border-bottom: 1px solid #ddd;
}
.progress {
  position: absolute;
  left: 0;
  bottom: -1px;
  width: 100%;
  height: 3px;
  background: #0f766e;
  transform-origin: left;
  transform: scaleX(var(--progress, 0));
}
.spacer {
  height: 80vh;
  display: grid;
  place-items: center;
  margin: 0;
}
.track {
  display: flex;
  gap: 1rem;
  height: calc(100vh - 64px);
  align-items: center;
  margin: 0;
  padding: 0 1.5rem;
  list-style: none;
  box-sizing: border-box;
}
.step {
  flex: 0 0 18rem;
  height: 12rem;
  display: grid;
  place-items: center;
  border-left: 3px solid #0f766e;
  background: #fbf1ef;
  font-size: 2rem;
}

JavaScript

main.js
// Called before the DOM is ready, this replaces the automatic start.
HorizontalScroll.auto({
  top: 64,
  speed: 1.5,
  onProgress: ({ progress }) =>
    document.querySelector('.progress').style.setProperty('--progress', progress),
})

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>Under a fixed header, with progress</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;
      }
      .bar-header {
        position: fixed;
        inset: 0 0 auto;
        z-index: 1;
        height: 64px;
        display: flex;
        align-items: center;
        padding: 0 1.5rem;
        background: #fff;
        border-bottom: 1px solid #ddd;
      }
      .progress {
        position: absolute;
        left: 0;
        bottom: -1px;
        width: 100%;
        height: 3px;
        background: #0f766e;
        transform-origin: left;
        transform: scaleX(var(--progress, 0));
      }
      .spacer {
        height: 80vh;
        display: grid;
        place-items: center;
        margin: 0;
      }
      .track {
        display: flex;
        gap: 1rem;
        height: calc(100vh - 64px);
        align-items: center;
        margin: 0;
        padding: 0 1.5rem;
        list-style: none;
        box-sizing: border-box;
      }
      .step {
        flex: 0 0 18rem;
        height: 12rem;
        display: grid;
        place-items: center;
        border-left: 3px solid #0f766e;
        background: #fbf1ef;
        font-size: 2rem;
      }
    </style>
  </head>
  <body>
    <main>
      <header class="bar-header">Timeline<span class="progress"></span></header>
      <p class="spacer">Scroll down</p>
      <section data-horizontal-scroll aria-label="Timeline">
        <ol data-horizontal-scroll-track class="track">
          <li class="step" tabindex="0">2017</li>
          <li class="step" tabindex="0">2018</li>
          <li class="step" tabindex="0">2019</li>
          <li class="step" tabindex="0">2020</li>
          <li class="step" tabindex="0">2021</li>
          <li class="step" tabindex="0">2022</li>
          <li class="step" tabindex="0">2023</li>
          <li class="step" tabindex="0">2024</li>
        </ol>
      </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>
      // Called before the DOM is ready, this replaces the automatic start.
      HorizontalScroll.auto({
        top: 64,
        speed: 1.5,
        onProgress: ({ progress }) =>
          document.querySelector('.progress').style.setProperty('--progress', progress),
      })
    </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>Under a fixed header, with progress</title>
    <link rel="stylesheet" href="./style.css" />
  </head>
  <body>
    <main>
      <header class="bar-header">Timeline<span class="progress"></span></header>
      <p class="spacer">Scroll down</p>
      <section data-horizontal-scroll aria-label="Timeline">
        <ol data-horizontal-scroll-track class="track">
          <li class="step" tabindex="0">2017</li>
          <li class="step" tabindex="0">2018</li>
          <li class="step" tabindex="0">2019</li>
          <li class="step" tabindex="0">2020</li>
          <li class="step" tabindex="0">2021</li>
          <li class="step" tabindex="0">2022</li>
          <li class="step" tabindex="0">2023</li>
          <li class="step" tabindex="0">2024</li>
        </ol>
      </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;
}
.bar-header {
  position: fixed;
  inset: 0 0 auto;
  z-index: 1;
  height: 64px;
  display: flex;
  align-items: center;
  padding: 0 1.5rem;
  background: #fff;
  border-bottom: 1px solid #ddd;
}
.progress {
  position: absolute;
  left: 0;
  bottom: -1px;
  width: 100%;
  height: 3px;
  background: #0f766e;
  transform-origin: left;
  transform: scaleX(var(--progress, 0));
}
.spacer {
  height: 80vh;
  display: grid;
  place-items: center;
  margin: 0;
}
.track {
  display: flex;
  gap: 1rem;
  height: calc(100vh - 64px);
  align-items: center;
  margin: 0;
  padding: 0 1.5rem;
  list-style: none;
  box-sizing: border-box;
}
.step {
  flex: 0 0 18rem;
  height: 12rem;
  display: grid;
  place-items: center;
  border-left: 3px solid #0f766e;
  background: #fbf1ef;
  font-size: 2rem;
}

JavaScript

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

autoHorizontalScroll({
  top: 64,
  speed: 1.5,
  onProgress: ({ progress }) =>
    document.querySelector('.progress').style.setProperty('--progress', progress),
})

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>Under a fixed header, with progress</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;
      }
      .bar-header {
        position: fixed;
        inset: 0 0 auto;
        z-index: 1;
        height: 64px;
        display: flex;
        align-items: center;
        padding: 0 1.5rem;
        background: #fff;
        border-bottom: 1px solid #ddd;
      }
      .progress {
        position: absolute;
        left: 0;
        bottom: -1px;
        width: 100%;
        height: 3px;
        background: #0f766e;
        transform-origin: left;
        transform: scaleX(var(--progress, 0));
      }
      .spacer {
        height: 80vh;
        display: grid;
        place-items: center;
        margin: 0;
      }
      .track {
        display: flex;
        gap: 1rem;
        height: calc(100vh - 64px);
        align-items: center;
        margin: 0;
        padding: 0 1.5rem;
        list-style: none;
        box-sizing: border-box;
      }
      .step {
        flex: 0 0 18rem;
        height: 12rem;
        display: grid;
        place-items: center;
        border-left: 3px solid #0f766e;
        background: #fbf1ef;
        font-size: 2rem;
      }
    </style>
  </head>
  <body>
    <main>
      <header class="bar-header">Timeline<span class="progress"></span></header>
      <p class="spacer">Scroll down</p>
      <section data-horizontal-scroll aria-label="Timeline">
        <ol data-horizontal-scroll-track class="track">
          <li class="step" tabindex="0">2017</li>
          <li class="step" tabindex="0">2018</li>
          <li class="step" tabindex="0">2019</li>
          <li class="step" tabindex="0">2020</li>
          <li class="step" tabindex="0">2021</li>
          <li class="step" tabindex="0">2022</li>
          <li class="step" tabindex="0">2023</li>
          <li class="step" tabindex="0">2024</li>
        </ol>
      </section>
      <p class="spacer">The end</p>
    </main>
    <script type="module">
      import { autoHorizontalScroll } from '@samline/horizontal-scroll'

      autoHorizontalScroll({
        top: 64,
        speed: 1.5,
        onProgress: ({ progress }) =>
          document.querySelector('.progress').style.setProperty('--progress', progress),
      })
    </script>
  </body>
</html>
03 / Wide screens only

A swipeable carousel on phones

Wide screens onlyLive preview

With data-horizontal-scroll-media the effect only runs on wide screens. Elsewhere, and with reduced motion, your CSS takes over: here a snapping carousel.

Scroll down

Card 1
Card 2
Card 3
Card 4
Card 5

The end

State: …. Narrow the window, or turn on reduced motion, to get the swipeable carousel.

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>A swipeable carousel on phones</title>
    <link rel="stylesheet" href="./style.css" />
  </head>
  <body>
    <main>
      <p class="spacer">Scroll down</p>
      <section
        data-horizontal-scroll
        data-horizontal-scroll-media="(min-width: 48rem)"
        aria-label="Products"
      >
        <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>
        </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
/* Phones and reduced motion: a native, snapping carousel. */
[data-horizontal-scroll] {
  overflow-x: auto;
  scroll-snap-type: x mandatory;
}
.card {
  scroll-snap-align: center;
}
/* Pinned: no snapping, the page scroll drives the row. */
[data-horizontal-scroll-state='active'] {
  scroll-snap-type: none;
}
body {
  margin: 0;
  font-family: system-ui, sans-serif;
}
.spacer {
  height: 80vh;
  display: grid;
  place-items: center;
  margin: 0;
}
.track {
  display: flex;
  gap: 1rem;
  padding: 2rem 1.5rem;
}
[data-horizontal-scroll-state='active'] .track {
  height: 100vh;
  align-items: center;
  box-sizing: border-box;
}
.card {
  flex: 0 0 min(80vw, 24rem);
  height: 18rem;
  display: grid;
  place-items: center;
  border-radius: 1rem;
  background: #e6f4ea;
  font-size: 1.5rem;
}

JavaScript

main.js
// Nothing to call: the media query comes from the attribute.

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>A swipeable carousel on phones</title>
    <style>
      /* Phones and reduced motion: a native, snapping carousel. */
      [data-horizontal-scroll] {
        overflow-x: auto;
        scroll-snap-type: x mandatory;
      }
      .card {
        scroll-snap-align: center;
      }
      /* Pinned: no snapping, the page scroll drives the row. */
      [data-horizontal-scroll-state='active'] {
        scroll-snap-type: none;
      }
      body {
        margin: 0;
        font-family: system-ui, sans-serif;
      }
      .spacer {
        height: 80vh;
        display: grid;
        place-items: center;
        margin: 0;
      }
      .track {
        display: flex;
        gap: 1rem;
        padding: 2rem 1.5rem;
      }
      [data-horizontal-scroll-state='active'] .track {
        height: 100vh;
        align-items: center;
        box-sizing: border-box;
      }
      .card {
        flex: 0 0 min(80vw, 24rem);
        height: 18rem;
        display: grid;
        place-items: center;
        border-radius: 1rem;
        background: #e6f4ea;
        font-size: 1.5rem;
      }
    </style>
  </head>
  <body>
    <main>
      <p class="spacer">Scroll down</p>
      <section
        data-horizontal-scroll
        data-horizontal-scroll-media="(min-width: 48rem)"
        aria-label="Products"
      >
        <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>
        </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 media query comes from the attribute.
    </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>A swipeable carousel on phones</title>
    <link rel="stylesheet" href="./style.css" />
  </head>
  <body>
    <main>
      <p class="spacer">Scroll down</p>
      <section
        data-horizontal-scroll
        data-horizontal-scroll-media="(min-width: 48rem)"
        aria-label="Products"
      >
        <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>
        </div>
      </section>
      <p class="spacer">The end</p>
    </main>
    <script type="module" src="./main.js"></script>
  </body>
</html>

CSS

style.css
/* Phones and reduced motion: a native, snapping carousel. */
[data-horizontal-scroll] {
  overflow-x: auto;
  scroll-snap-type: x mandatory;
}
.card {
  scroll-snap-align: center;
}
/* Pinned: no snapping, the page scroll drives the row. */
[data-horizontal-scroll-state='active'] {
  scroll-snap-type: none;
}
body {
  margin: 0;
  font-family: system-ui, sans-serif;
}
.spacer {
  height: 80vh;
  display: grid;
  place-items: center;
  margin: 0;
}
.track {
  display: flex;
  gap: 1rem;
  padding: 2rem 1.5rem;
}
[data-horizontal-scroll-state='active'] .track {
  height: 100vh;
  align-items: center;
  box-sizing: border-box;
}
.card {
  flex: 0 0 min(80vw, 24rem);
  height: 18rem;
  display: grid;
  place-items: center;
  border-radius: 1rem;
  background: #e6f4ea;
  font-size: 1.5rem;
}

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>A swipeable carousel on phones</title>
    <style>
      /* Phones and reduced motion: a native, snapping carousel. */
      [data-horizontal-scroll] {
        overflow-x: auto;
        scroll-snap-type: x mandatory;
      }
      .card {
        scroll-snap-align: center;
      }
      /* Pinned: no snapping, the page scroll drives the row. */
      [data-horizontal-scroll-state='active'] {
        scroll-snap-type: none;
      }
      body {
        margin: 0;
        font-family: system-ui, sans-serif;
      }
      .spacer {
        height: 80vh;
        display: grid;
        place-items: center;
        margin: 0;
      }
      .track {
        display: flex;
        gap: 1rem;
        padding: 2rem 1.5rem;
      }
      [data-horizontal-scroll-state='active'] .track {
        height: 100vh;
        align-items: center;
        box-sizing: border-box;
      }
      .card {
        flex: 0 0 min(80vw, 24rem);
        height: 18rem;
        display: grid;
        place-items: center;
        border-radius: 1rem;
        background: #e6f4ea;
        font-size: 1.5rem;
      }
    </style>
  </head>
  <body>
    <main>
      <p class="spacer">Scroll down</p>
      <section
        data-horizontal-scroll
        data-horizontal-scroll-media="(min-width: 48rem)"
        aria-label="Products"
      >
        <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>
        </div>
      </section>
      <p class="spacer">The end</p>
    </main>
    <script type="module">
      import { autoHorizontalScroll } from '@samline/horizontal-scroll'

      autoHorizontalScroll()
    </script>
  </body>
</html>

These examples show a few possibilities. The next ideas are yours: combine the package’s capabilities with your own content, design and interactions to create the experience your project needs.

Read the example guideDownload the Horizontal Scroll skill for AI agents
@samline/horizontal-scroll

Pin a section and move its content sideways as the page scrolls down, with keyboard focus, a no-JavaScript fallback, media queries and reduced motion, for vanilla JavaScript, any framework and plain HTML.

v1.0.1·MIT

Explore

DocsInstallation guideWorking examples

Project

Horizontal Scroll skill for AI agentsGitHub(opens in a new tab)Changelognpm(opens in a new tab)License(opens in a new tab)

© 2026 samline · Made for the open web.

Back to top