Buttons and dots
Spill draws no controls — you build previous and next buttons, dots and a progress bar from the API in a few lines, or let attributes build them.
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();
});The Basic example: two buttons and a dot for each snap, wired to the API. Each piece is below, then the same controls written as attributes.
Previous and next
scrollPrev() and scrollNext() move one snap back or forward. canScrollPrev() and canScrollNext() say whether there’s a snap to go to, so a button can turn off at an edge.
const prev = root.querySelector(".prev");
const next = root.querySelector(".next");
prev.addEventListener("click", () => api.scrollPrev());
next.addEventListener("click", () => api.scrollNext());
const toggleButtons = () => {
prev.disabled = !api.canScrollPrev();
next.disabled = !api.canScrollNext();
};
api.on("init", toggleButtons).on("select", toggleButtons).on("reInit", toggleButtons);
Three events keep the buttons right:
init— the carousel is built. It fires on the next task, so a listener added right afterSpill()hears it.select— the selected snap changed: a button, a dot, a mouse’s drag, or a hand’s scroll as soon as another snap is the nearest.reInit— the carousel was rebuilt: a new size, a breakpoint, slides added or removed. The snaps may have changed with it.
Both checks follow the selected snap, not the scroll position, and both are false while the carousel is off (active: false). A move is one snap, which can be several slides with slidesToScroll. Pass true to jump without the animation: scrollNext(true).
disabled or aria-disabled
The Basic example sets disabled. It’s the simplest: the browser skips the button and ignores its clicks. But a focused button that becomes disabled loses its focus, so a keyboard user who presses Next up to the last slide loses their place.
aria-disabled="true" keeps the button in the tab order and still tells assistive technology it’s off. It doesn’t stop clicks, so check it in the handler:
const toggleButtons = () => {
prev.setAttribute("aria-disabled", String(!api.canScrollPrev()));
next.setAttribute("aria-disabled", String(!api.canScrollNext()));
};
prev.addEventListener("click", () => {
if (prev.getAttribute("aria-disabled") !== "true") api.scrollPrev();
});
next.addEventListener("click", () => {
if (next.getAttribute("aria-disabled") !== "true") api.scrollNext();
});
.prev:disabled,
.next:disabled,
.prev[aria-disabled="true"],
.next[aria-disabled="true"] {
opacity: 0.35;
cursor: default;
}
The attributes layer works this way: aria-disabled at an edge, plus a data-spill-disabled attribute to style.
Dots
scrollSnapList() returns one number for each snap: its place, from 0 at the start to 1 at the end. For dots, only the count matters. Make a button for each, and send a click to scrollTo(index).
const dots = root.querySelector(".dots");
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 = () => {
const selected = api.selectedScrollSnap();
[...dots.children].forEach((dot, index) => dot.setAttribute("aria-current", String(index === selected)));
};
const refresh = () => {
buildDots();
selectDot();
};
api.on("init", refresh).on("reInit", refresh).on("select", selectDot);
- Build them on
initandreInit. The number of snaps isn’t fixed. A new size, a breakpoint, or a slide added or removed can change it, and each of these ends inreInit. - Mark the selected one on
select.aria-current="true"tells assistive technology which dot is current, and gives your CSS its hook:.dots > [aria-current="true"]. - Label them. A dot is a button with no text, so its
aria-labelsays where it goes. WithslidesToScrollabove 1 a dot stands for several slides, and “Go to page 2” may read better.
A progress bar
scrollProgress() says where the scroll is: 0 at the start, 1 at the end. Read it on scroll, which Spill fires once a frame however the carousel moves — a finger, a trackpad, a mouse’s drag or a button.
Progress
<div class="carousel carousel--progress">
<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 class="carousel__slide"><div class="carousel__card">6</div></div>
<div class="carousel__slide"><div class="carousel__card">7</div></div>
<div class="carousel__slide"><div class="carousel__card">8</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__progress" aria-hidden="true">
<div class="carousel__progress-bar"></div>
</div>
</div>
</div>/* Narrower, shorter slides: more of them show */
.carousel--progress {
--slide-size: min(60%, 16rem);
--slide-height: 10rem;
}
/* The track: where the dots would be */
.carousel--progress .carousel__progress {
flex: 0 1 12rem;
height: 0.3rem;
overflow: hidden;
border-radius: 1rem;
background: var(--line-strong, #3a3a42);
}
/* The bar: --progress (0 to 1) is written by the script as it scrolls. A scale, not a width: nothing is laid out
again on a scroll. */
.carousel--progress .carousel__progress-bar {
height: 100%;
background: var(--accent, #9368f0);
transform: scaleX(var(--progress, 0));
transform-origin: left;
}import Spill from "@bozdev/spill";
const root = document.querySelector(".carousel--progress");
const prev = root.querySelector(".carousel__button--prev");
const next = root.querySelector(".carousel__button--next");
const bar = root.querySelector(".carousel__progress-bar");
const api = Spill(root.querySelector(".carousel__viewport"), { align: "start" });
// The bar: where the scroll is, 0 (the start) to 1 (the end), as a CSS variable the CSS scales the bar by.
// "scroll" comes once a frame, whatever moves it: a finger, a trackpad, a mouse's drag or the buttons.
const showProgress = () => bar.style.setProperty("--progress", String(api.scrollProgress()));
// 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();
};
// On init and reInit (a new size changes the scroll's length) both are brought up to date
const refresh = () => {
showProgress();
toggleButtons();
};
api.on("init", refresh).on("reInit", refresh).on("scroll", showProgress).on("select", toggleButtons);const bar = root.querySelector(".progress-bar");
const showProgress = () => bar.style.setProperty("--progress", String(api.scrollProgress()));
api.on("init", showProgress).on("reInit", showProgress).on("scroll", showProgress);
.progress {
height: 0.3rem;
overflow: hidden;
background: #ddd;
}
.progress-bar {
height: 100%;
background: currentColor;
transform: scaleX(var(--progress, 0));
transform-origin: left;
}
The bar changes on every frame of a scroll. A scale, unlike a width, lays nothing out again. reInit matters here too: a new size changes how far the carousel can scroll. When nothing overflows, scrollProgress() is 0. In a right-to-left carousel, set transform-origin: right.
The example’s bar has aria-hidden="true": it only repeats what the scroll position already shows.
By attributes
With the attributes layer, the same controls are markup. Mark the elements, load @bozdev/spill/auto, and it wires them: inside the carousel, or anywhere on the page with data-spill-for.
<section id="gallery" data-spill-carousel='{"align":"start"}' aria-label="Gallery">
<div class="viewport" data-spill-viewport>
<div class="container">…</div>
</div>
<button type="button" data-spill-prev>…</button>
<button type="button" data-spill-next>…</button>
<div class="dots" data-spill-dots></div>
<div class="progress" data-spill-progress><span></span></div>
</section>
<button type="button" data-spill-next data-spill-for="gallery">Next</button>
import "@bozdev/spill/auto";
| Attribute | What you get |
|---|---|
data-spill-prev, data-spill-next |
A click moves one snap. At an edge, aria-disabled="true" and data-spill-disabled, and a click there does nothing. An aria-label (“Previous slide”, “Next slide”) unless the button has one |
data-spill-dots |
Filled with a button for each snap and rebuilt on reInit. Each has data-spill-dot (its index) and an aria-label; the selected one has aria-current="true". data-spill-dots="number" puts the numbers in them |
data-spill-progress |
A --spill-progress CSS variable, from 0 to 1, kept up to date as it scrolls |
data-spill-to="3" |
A click goes to the third snap |
data-spill-for="gallery" |
Ties a control outside the carousel to it, by the carousel’s id |
[data-spill-disabled] { opacity: 0.35; }
[data-spill-dots] > [aria-current="true"] { background: currentColor; }
.progress > span {
display: block;
height: 100%;
background: currentColor;
transform: scaleX(var(--spill-progress, 0));
transform-origin: left;
}
The variable is set on the element with data-spill-progress and inherited, so the bar can be a child of it.
More by attributes
A data-spill-play button turns Autoplay on and off, and the labels can be in your site’s language. By attributes has all of it.