Quick start
A carousel step by step — the markup, the CSS, one call, its events, then buttons and dots.
Install Spill first — npm install @bozdev/spill, or a <script> tag (Installation). Then build a carousel in five steps.
The markup
Three levels: a viewport, the box that scrolls; its first child, the container; and the container’s children, the slides.
<div class="viewport">
<div class="container">
<div class="slide">1</div>
<div class="slide">2</div>
<div class="slide">3</div>
<div class="slide">4</div>
<div class="slide">5</div>
</div>
</div>
Any elements will do — a <ul> of <li>s, a <section> of <figure>s. The class names are yours; Spill finds the container and the slides by their place (the container and slides options name others).
The CSS
The look is your CSS, as with Embla. A row of slides, each 80% of the viewport, 1rem apart:
.viewport { overflow-x: auto; } /* before (and without) JavaScript, the row still scrolls */
.container { display: flex; gap: 1rem; }
.slide { flex: 0 0 80%; min-width: 0; }
.viewport[data-spill-draggable] { cursor: grab; }
.viewport[data-spill-dragging] { cursor: grabbing; }
A slide’s flex-basis is its size: 100% shows one at a time, calc((100% - 2rem) / 3) three with a 1rem gap. Spill reads the sizes and never sets them, so change them in media queries as you like.
Spill writes what it needs to work inline — the overflow, the snap type, each snap’s snap point — and takes it away again on destroy(). The two attributes above are hooks it sets for your CSS: data-spill-draggable while a mouse can drag the carousel, data-spill-dragging while it does. More in Markup and CSS.
The call
Give Spill() the viewport:
import Spill from "@bozdev/spill";
const viewport = document.querySelector(".viewport");
const api = Spill(viewport, { align: "start" });
Spill(viewport, options, plugins) builds the carousel and returns its API. The options are Embla’s — here align: "start" puts each snap at the viewport’s start (the default is "center"). Plugins come third, in an array: [Autoplay()]. With the <script> tag, Spill is a global: leave out the import.
When the carousel leaves the page, take it down:
api.destroy();
Events
The carousel reports what it does. Listen with on():
api.on("select", () => {
console.log("Selected snap:", api.selectedScrollSnap());
});
api.on("settle", () => console.log("At rest"));
A listener gets the API and the event’s name: (api, eventName). on() returns the API, so calls chain; off(event, listener) removes one. The ones you’ll use most:
| Event | When |
|---|---|
init |
Built — on the next task after Spill() returns, so a listener added right after the call hears it |
select |
The selected snap changed |
scroll |
It scrolled (once a frame) |
settle |
It came to rest |
reInit |
Rebuilt: a new size, a breakpoint, slides added or removed, reInit() |
Every event is on the Events page.
Buttons and dots
Add the controls to the markup — anywhere, they’re plain buttons:
<div class="carousel">
<div class="viewport">…</div>
<button class="prev" type="button">Previous</button>
<button class="next" type="button">Next</button>
<div class="dots"></div>
</div>
Then wire them to the API:
const prev = document.querySelector(".prev");
const next = document.querySelector(".next");
const dots = document.querySelector(".dots");
prev.addEventListener("click", () => api.scrollPrev());
next.addEventListener("click", () => api.scrollNext());
// 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;
}),
);
};
// The selected dot marked, the buttons off at the edges
const update = () => {
[...dots.children].forEach((dot, index) => {
dot.setAttribute("aria-current", String(index === api.selectedScrollSnap()));
});
prev.disabled = !api.canScrollPrev();
next.disabled = !api.canScrollNext();
};
const refresh = () => {
buildDots();
update();
};
api.on("init", refresh).on("reInit", refresh).on("select", update);
A snap is a place the carousel comes to rest. It isn’t always one slide: with slidesToScroll, or slides that fit together at an edge, one snap can hold several. So the dots follow scrollSnapList(), not the slides — and they’re built again on reInit, since a new size, a breakpoint or a new slide can change the snaps.
Style the selected dot with [aria-current="true"], and the buttons with :disabled.
Keep the focus
A disabled button loses the keyboard’s focus. Set aria-disabled="true" instead and ignore its clicks, and a focused button keeps its focus at the edge — the way By attributes does it.
All together
The same steps, live — with the examples’ class names and look. Its code is in the tabs.
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();
});Where next
- By attributes — the same carousel with no script of your own: buttons, dots and plugins in the markup.
- Options, Methods, Events and Plugins — the whole API.
- Buttons and dots and Breakpoints — the guides.
- Frameworks — React, Vue, Svelte, Solid and Astro.