Introduction
Spill is a carousel on the browser's own scroll — Embla Carousel's API, options, events and plugins, with native scroll underneath.
Basic
<div class="carousel carousel--basic">
<div class="carousel__viewport">
<div class="carousel__container">
<div class="carousel__slide"><div class="carousel__card">1</div></div>
<div class="carousel__slide"><div class="carousel__card">2</div></div>
<div class="carousel__slide"><div class="carousel__card">3</div></div>
<div class="carousel__slide"><div class="carousel__card">4</div></div>
<div class="carousel__slide"><div class="carousel__card">5</div></div>
</div>
</div>
<div class="carousel__controls">
<div class="carousel__buttons">
<button class="carousel__button carousel__button--prev" type="button" aria-label="Previous slide">
<svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m15 18-6-6 6-6" /></svg>
</button>
<button class="carousel__button carousel__button--next" type="button" aria-label="Next slide">
<svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m9 18 6-6-6-6" /></svg>
</button>
</div>
<div class="carousel__dots"></div>
</div>
</div>import Spill from "@bozdev/spill";
const root = document.querySelector(".carousel--basic");
const prev = root.querySelector(".carousel__button--prev");
const next = root.querySelector(".carousel__button--next");
const dots = root.querySelector(".carousel__dots");
const api = Spill(root.querySelector(".carousel__viewport"), { align: "start" });
// Previous and next: a snap each, off at the edges
prev.addEventListener("click", () => api.scrollPrev());
next.addEventListener("click", () => api.scrollNext());
const toggleButtons = () => {
prev.disabled = !api.canScrollPrev();
next.disabled = !api.canScrollNext();
};
// A dot for each snap
const buildDots = () => {
dots.replaceChildren(
...api.scrollSnapList().map((_, index) => {
const dot = document.createElement("button");
dot.type = "button";
dot.setAttribute("aria-label", `Go to slide ${index + 1}`);
dot.addEventListener("click", () => api.scrollTo(index));
return dot;
}),
);
};
const selectDot = () => {
[...dots.children].forEach((dot, index) => dot.setAttribute("aria-current", String(index === api.selectedScrollSnap())));
};
const refresh = () => {
buildDots();
selectDot();
toggleButtons();
};
api.on("init", refresh).on("reInit", refresh).on("select", () => {
selectDot();
toggleButtons();
});Nothing here is moved with a transform: the viewport really scrolls. A finger’s momentum, a trackpad, the keyboard’s focus, find-in-page and screen readers all work as they do on any scrolling box. The browser’s CSS snap points do the snapping; Spill measures, animates and reports.
- Embla’s API. The same options, methods, events and plugin shape — code written for Embla mostly runs as it is (Coming from Embla).
- No dependencies, no stylesheet. What it needs to work it writes inline, and takes away again on
destroy(). The look stays yours. - Plugins. Autoplay, Class names and Auto height, with Embla’s options, methods and events — or your own.
- By attributes. Write the markup and the carousel builds itself; its controls can be anywhere on the page (By attributes).
- Small. The core is 12.6 KB minified, 4.9 KB gzip — Embla’s is 17.9 KB / 7.2 KB. Each part is its own module.
Why native scroll
Embla — and most carousels — move a track with transform and rebuild scrolling in JavaScript: the drag, the momentum, the snapping. That was the dependable way when they were written: scroll-snap was uneven across browsers, Safari’s smooth scrolling came late, there was no scrollend event. Today the browser does all of it, and does it better where it matters most: under a finger.
| Native scroll (Spill) | Transform (Embla) | |
|---|---|---|
| A finger’s momentum, iOS bounce | The browser’s own | Imitated |
| Trackpad, shift + wheel | Works | Needs a plugin |
| Mouse drag | Spill does it | Built in |
| The keyboard’s focus brings a slide in | By itself | Handled separately |
| Find in page reaches a slide | Yes | No |
| Before or without JavaScript | Scrollable, readable | A clipped row |
| Scrolling performance | On the compositor | Main thread while dragging |
| Snapping | CSS scroll snap | JS physics |
| Scroll-driven effects | CSS animation-timeline |
JS |
| Lazy images | loading="lazy" |
Separately |
| Seamless infinite loop | Not here | Natural |
| Duration and easing of programmatic moves | Spill animates it (duration) |
Full control |
| Code | Smaller (the browser does the work) | Larger |
No loop
A seamless infinite loop needs the slides moved around behind the user’s back — natural with a transform, a fight with a real scroll position. Spill leaves it out. Autoplay goes back to the first snap at the end instead.
How it works
You give Spill the viewport — the box that scrolls. Its first child is the container, and the container’s children are the slides:
<div class="viewport"> <!-- the box that scrolls: Spill(viewport, …) -->
<div class="container"> <!-- its first child (or options.container) -->
<div class="slide">…</div> <!-- the container's children (or options.slides) -->
</div>
</div>
Spill measures the slides and groups them into snaps — the places the carousel comes to rest. It writes CSS snap points on each snap’s first slide, so a finger or a trackpad stops exactly there, natively. A mouse drags it, buttons call scrollNext() and scrollPrev(), and every move is reported as an event: select when the selected snap changes, scroll as it scrolls, settle when it comes to rest.
Where next
- Installation — npm, a
<script>tag, ES modules. - Quick start — a carousel in a few lines.
- By attributes — a carousel with no script of your own.
- Examples — each one live, with its code.