Pin a section and move its row of content sideways as the page scrolls down, for galleries, timelines and showcases, with keyboard focus, media queries, reduced motion and a native scroll fallback. For vanilla JavaScript, any framework and plain HTML.
Demo · Examples · Documentation · Changelog
- Installation
- Quick start
- HTML / CDN
- Capabilities
- API at a glance
- Documentation
- Changelog
- AI agent skill
- License
npm install @samline/horizontal-scrollpnpm add @samline/horizontal-scrollbun add @samline/horizontal-scrollAny modern browser with position: sticky; without JavaScript the row keeps your CSS. On the server, every function is inert. No runtime dependencies.
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);
}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>The bundle defines window.HorizontalScroll. Add data-manual to the script tag and call HorizontalScroll.auto(options) to start it with your own options.
The section grows exactly tall enough to cross its row, the row pins with position: sticky, and its translate follows the page scroll once per frame. Wheel, touch, keys and scrollbars keep working as usual; at the end, the page carries on.
Without JavaScript, outside your media query or when the visitor prefers reduced motion, nothing is pinned or resized and the section is left to your CSS, such as a native swipeable row. data-horizontal-scroll-state tells the two states apart.
When focus lands on a card that is off to the side, the page scrolls until it is fully in view, so keyboard users never lose track of focus.
Pin below a fixed header (top), cross faster or slower (speed), work inside a scroll container (root), and drive progress bars with the --horizontal-scroll-progress variable or onProgress. Images and fonts that change the row's size are measured again on their own.
| API | Purpose |
|---|---|
autoHorizontalScroll(options?) |
Set up every [data-horizontal-scroll], including sections added later. |
horizontalScroll(section, options?) |
Set up one section. Returns { active, progress, refresh, destroy }. |
onProgress(state) |
The progress changed: { progress, x, distance }. |
data-horizontal-scroll-* attributes |
Track, top, speed, media and focus per section. |
| Entrypoint | When to use |
|---|---|
@samline/horizontal-scroll |
ESM or CommonJS, horizontalScroll and autoHorizontalScroll. |
@samline/horizontal-scroll/vanilla |
horizontalScroll as the default export. |
@samline/horizontal-scroll/browser |
Classic script that defines window.HorizontalScroll. |
Read the documentation for the full guides and API contracts, and explore working examples with complete and separate source files.
| Guide | What it covers |
|---|---|
| Installation | npm, CDN and the first section. |
| API reference | horizontalScroll, autoHorizontalScroll and window.HorizontalScroll. |
| Options | Attributes and options. |
| Layouts | Headers, fallbacks, focus, scroll containers and sticky pitfalls. |
| Frameworks | React, Vue, Svelte, Astro and page swaps. |
Read CHANGELOG.md or the published changelog for release history and explicitly marked breaking and behavior changes. Review the notes before upgrading.
The Horizontal Scroll skill teaches verified package integration. Its maintained repository source and website download are the same file. Verify the installed package version before applying its guidance.
Download SKILL.md into a horizontal-scroll/ folder in your agent's supported skill directory. For agents that discover project skills from .agents/skills/:
mkdir -p .agents/skills/horizontal-scroll
curl --fail --location https://samline.github.io/horizontal-scroll/skills/horizontal-scroll/SKILL.md \
--output .agents/skills/horizontal-scroll/SKILL.mdKeep the filename SKILL.md; discovery paths and invocation syntax depend on the agent.
MIT — LICENSE.md.