Examples
Each one live, with its code. They share one stylesheet — the look is yours; Spill only scrolls.
The examples share one stylesheet for the look; each adds its own touches. Drag them with a mouse, scroll them with a trackpad or a finger, reach them with the keyboard.
Basic
A row of slides with previous and next buttons and a dot for each snap — the API's way.
<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();
});Align
Where a snap sits in the viewport — start, center or end — switched live with reInit, the selected snap kept.
<div class="carousel carousel--align">
<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__align" role="group" aria-label="Align">
<button type="button" data-align="start" aria-pressed="false">Start</button>
<button type="button" data-align="center" aria-pressed="true">Center</button>
<button type="button" data-align="end" aria-pressed="false">End</button>
</div>
</div>
</div>/* Narrower slides, so the three places differ more */
.carousel--align {
--slide-size: 60%;
}
.carousel--align .carousel__controls {
flex-wrap: wrap;
}
/* The switch: one pill, the chosen part filled */
.carousel--align .carousel__align {
display: flex;
gap: 0.15rem;
padding: 0.25rem;
border-radius: 999px;
box-shadow: inset 0 0 0 1px var(--line-strong, #3a3a42);
}
.carousel--align .carousel__align button {
height: 2rem;
padding: 0 0.9rem;
border: 0;
border-radius: 999px;
font: 600 0.85rem/1 var(--font-sans, system-ui);
color: var(--muted, #a0a0aa);
background: none;
cursor: pointer;
}
.carousel--align .carousel__align button:hover {
color: var(--text, #e6e6ec);
}
.carousel--align .carousel__align button[aria-pressed="true"] {
color: var(--on-accent, #fff);
background: var(--accent, #9368f0);
}import Spill from "@bozdev/spill";
const root = document.querySelector(".carousel--align");
const prev = root.querySelector(".carousel__button--prev");
const next = root.querySelector(".carousel__button--next");
const choices = [...root.querySelectorAll("[data-align]")];
// It starts on the second snap: the scroll can't go before its start, so at the first snap every align
// looks the same (unless containScroll: false) — the difference shows from the middle on
const api = Spill(root.querySelector(".carousel__viewport"), { align: "center", startIndex: 1 });
// The switch: the carousel rebuilt with the new align (reInit keeps the selected snap)
for (const choice of choices) {
choice.addEventListener("click", () => {
api.reInit({ align: choice.dataset.align });
choices.forEach((each) => each.setAttribute("aria-pressed", String(each === choice)));
});
}
// 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();
};
api.on("init", toggleButtons).on("reInit", toggleButtons).on("select", toggleButtons);Slides to scroll
Several slides in view and a snap a page: slidesToScroll "auto" groups as many as fit — two in a narrow carousel, three in a wide one.
<div class="carousel carousel--slides-to-scroll">
<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 slides">
<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 slides">
<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>/* Two slides in view; three once the carousel is wide enough (a container query: the carousel's width, not the
window's). Spill only reads these sizes — with slidesToScroll "auto" its snaps follow them. */
.carousel--slides-to-scroll {
--slide-size: calc((100% - var(--slide-spacing)) / 2);
--slide-height: 9rem;
container-type: inline-size;
}
@container (min-width: 32rem) {
.carousel--slides-to-scroll .carousel__slide {
--slide-size: calc((100% - 2 * var(--slide-spacing)) / 3);
}
}import Spill from "@bozdev/spill";
const root = document.querySelector(".carousel--slides-to-scroll");
const prev = root.querySelector(".carousel__button--prev");
const next = root.querySelector(".carousel__button--next");
const dots = root.querySelector(".carousel__dots");
// A snap a page: as many slides as fit in view ("auto"). A number groups that many: slidesToScroll: 2
const api = Spill(root.querySelector(".carousel__viewport"), { align: "start", slidesToScroll: "auto" });
// Previous and next: a page 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 — fewer than the slides. When the carousel changes width and a page holds two slides
// instead of three, Spill measures again and fires reInit: the dots are built again there.
const buildDots = () => {
dots.replaceChildren(
...api.scrollSnapList().map((_, index) => {
const dot = document.createElement("button");
dot.type = "button";
dot.setAttribute("aria-label", `Go to page ${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();
});Drag free
No snapping: thrown with a mouse or a finger, the row glides and stops where it stops.
<div class="carousel carousel--drag-free">
<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 class="carousel__slide"><div class="carousel__card">9</div></div>
<div class="carousel__slide"><div class="carousel__card">10</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>
</div>/* Smaller slides: a long row to throw */
.carousel--drag-free {
--slide-size: 40%;
--slide-height: 10rem;
}import Spill from "@bozdev/spill";
const root = document.querySelector(".carousel--drag-free");
const prev = root.querySelector(".carousel__button--prev");
const next = root.querySelector(".carousel__button--next");
// dragFree: no snap points — a throw glides on and the row rests wherever it ends
const api = Spill(root.querySelector(".carousel__viewport"), { align: "start", dragFree: true });
// The snaps are still there for the API: the buttons step one at a time, and the selected snap follows the
// nearest one as the row moves
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("reInit", toggleButtons).on("select", toggleButtons);Skip snaps
A strong throw passes several snaps and stops where its momentum runs out; a gentle one moves a single snap.
<div class="carousel carousel--skip-snaps">
<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 class="carousel__slide"><div class="carousel__card">9</div></div>
<div class="carousel__slide"><div class="carousel__card">10</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>/* Smaller slides: more snaps within a throw's reach */
.carousel--skip-snaps {
--slide-size: 45%;
--slide-height: 10rem;
}import Spill from "@bozdev/spill";
const root = document.querySelector(".carousel--skip-snaps");
const prev = root.querySelector(".carousel__button--prev");
const next = root.querySelector(".carousel__button--next");
const dots = root.querySelector(".carousel__dots");
// skipSnaps: a strong throw may pass several snaps. Without it, a throw moves one snap at most
// (under a finger, the browser's scroll-snap-stop: always)
const api = Spill(root.querySelector(".carousel__viewport"), { align: "start", skipSnaps: true });
// 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: it shows how far a throw went
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();
});Variable widths
Slides of different widths, each its own snap and centered when it's selected (the first and the last held to the edges) — Spill reads the sizes from your CSS.
<div class="carousel carousel--variable-widths">
<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>
</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>/* Each slide its own width. base.css sizes a slide with flex: 0 0 var(--slide-size), so setting the variable on a
slide is enough. Spill reads these sizes; it never sets them. */
.carousel--variable-widths .carousel__slide:nth-child(1) {
--slide-size: 45%;
}
.carousel--variable-widths .carousel__slide:nth-child(2) {
--slide-size: 70%;
}
.carousel--variable-widths .carousel__slide:nth-child(3) {
--slide-size: 30%;
}
.carousel--variable-widths .carousel__slide:nth-child(4) {
--slide-size: 55%;
}
.carousel--variable-widths .carousel__slide:nth-child(5) {
--slide-size: 40%;
}
.carousel--variable-widths .carousel__slide:nth-child(6) {
--slide-size: 65%;
}
.carousel--variable-widths .carousel__slide:nth-child(7) {
--slide-size: 35%;
}import Spill from "@bozdev/spill";
const root = document.querySelector(".carousel--variable-widths");
const prev = root.querySelector(".carousel__button--prev");
const next = root.querySelector(".carousel__button--next");
const dots = root.querySelector(".carousel__dots");
// Each slide is a snap, centered whatever its width. At the ends, the first and the last
// slide hold to the edges instead (containScroll: "trimSnaps", the default).
const api = Spill(root.querySelector(".carousel__viewport"), { align: "center" });
// 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();
});Vertical
A column: axis "y", a viewport with a fixed height, and the container's flex-direction set to column.
<div class="carousel carousel--vertical">
<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="m18 15-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="m6 9 6 6 6-6" /></svg>
</button>
</div>
<div class="carousel__dots"></div>
</div>
</div>/* The carousel beside its controls */
.carousel--vertical {
--slide-size: 75%;
display: flex;
gap: 1rem;
}
/* A column needs a height to scroll in: the viewport's is fixed, and the slides' sizes are shares of it */
.carousel--vertical .carousel__viewport {
flex: 1;
height: 22rem;
overflow-x: hidden;
overflow-y: auto; /* before JavaScript (and without it) the column still scrolls */
}
.carousel--vertical .carousel__container {
flex-direction: column;
height: 100%;
}
.carousel--vertical .carousel__card {
height: 100%;
}
/* The controls: a column too */
.carousel--vertical .carousel__controls {
flex-direction: column;
justify-content: center;
margin-top: 0;
}
.carousel--vertical .carousel__buttons,
.carousel--vertical .carousel__dots {
flex-direction: column;
}import Spill from "@bozdev/spill";
const root = document.querySelector(".carousel--vertical");
const prev = root.querySelector(".carousel__button--prev");
const next = root.querySelector(".carousel__button--next");
const dots = root.querySelector(".carousel__dots");
// axis "y": the viewport scrolls up and down. The column itself is the CSS's (style.css).
const api = Spill(root.querySelector(".carousel__viewport"), { axis: "y", 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();
});Right to left
direction "rtl" with dir="rtl" on the carousel: the first slide on the right, the next one to its left, and the buttons mirrored.
<div class="carousel carousel--right-to-left" dir="rtl">
<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="m9 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="m15 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--right-to-left");
const prev = root.querySelector(".carousel__button--prev");
const next = root.querySelector(".carousel__button--next");
const dots = root.querySelector(".carousel__dots");
// direction "rtl" goes with dir="rtl" in the markup (on the viewport or, as here, an ancestor):
// the one lays the row out from the right, the other tells Spill to read the scroll that way.
const api = Spill(root.querySelector(".carousel__viewport"), { align: "start", direction: "rtl" });
// Previous and next: a snap each, off at the edges (the row mirrors them: previous on the right)
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, the first one on the right
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();
});Breakpoints
One slide per view on a phone, two on a tablet, three on a desktop, and from 1440px Spill steps aside for a grid. Resize the window to try it: the dots follow each change.
<div class="carousel carousel--breakpoints">
<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>
</div>
<div class="carousel__controls">
<div class="carousel__buttons">
<button class="carousel__button carousel__button--prev" type="button" aria-label="Previous slides">
<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 slides">
<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>/* The slides per view are the CSS's; the script's breakpoints use the same media queries */
.carousel--breakpoints {
--slide-height: 10rem;
--slide-size: 100%; /* a phone: one slide per view */
}
@media (min-width: 640px) {
.carousel--breakpoints {
--slide-size: calc((100% - var(--slide-spacing)) / 2); /* a tablet: two */
}
}
@media (min-width: 1024px) {
.carousel--breakpoints {
--slide-size: calc((100% - 2 * var(--slide-spacing)) / 3); /* a desktop: three */
}
}
/* From 1440px the carousel is off (active: false): Spill has taken back everything it wrote, so this CSS alone lays
the slides out — a grid, and no controls */
@media (min-width: 1440px) {
.carousel--breakpoints .carousel__container {
display: grid;
grid-template-columns: repeat(3, minmax(0, 1fr));
}
.carousel--breakpoints .carousel__controls {
display: none;
}
}import Spill from "@bozdev/spill";
const root = document.querySelector(".carousel--breakpoints");
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",
// Each query's options are merged in, in this order, while it matches. When one starts or stops
// matching, the carousel is rebuilt (reInit), its selected snap kept.
breakpoints: {
"(min-width: 640px)": { slidesToScroll: 2 }, // two slides in view: two a move
"(min-width: 1024px)": { slidesToScroll: 3 }, // three in view: three a move
"(min-width: 1440px)": { active: false }, // off: all it wrote taken back, only the queries watched
},
});
// 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: six, three or two of them — none while the carousel is off
const buildDots = () => {
dots.replaceChildren(
...api.scrollSnapList().map((_, index) => {
const dot = document.createElement("button");
dot.type = "button";
dot.setAttribute("aria-label", `Go to page ${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())));
};
// reInit follows every breakpoint change (and a new size): the dots are built again for the new snaps
const refresh = () => {
buildDots();
selectDot();
toggleButtons();
};
api.on("init", refresh).on("reInit", refresh).on("select", () => {
selectDot();
toggleButtons();
});Progress
A bar under the carousel that fills as it scrolls, from scrollProgress() on every scroll event: by hand, with a mouse or with the buttons.
<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);Events
Every event the carousel fires, written down as it happens — newest first, the same event again counted on its line.
<div class="carousel carousel--events">
<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>
<ol class="carousel__log" aria-label="Events, newest first"></ol>
</div>/* The log: six lines, a fixed height — a new line never moves the page */
.carousel--events .carousel__log {
display: grid;
grid-auto-rows: 1.5rem;
box-sizing: border-box;
height: 10.5rem;
margin: 1rem 0 0;
padding: 0.75rem 1rem;
overflow: hidden;
border-radius: 1rem;
list-style: none;
font: 0.8rem/1.5rem var(--font-mono, monospace);
color: var(--muted, #a0a0aa);
background: var(--surface-2, #18181c);
}
.carousel--events .carousel__log li {
display: flex;
gap: 0.75rem;
margin: 0;
white-space: nowrap;
}
.carousel--events .carousel__log-name {
flex: 0 0 15ch;
color: var(--accent-text, #b39af7);
}
.carousel--events .carousel__log-detail {
min-width: 0;
overflow: hidden;
text-overflow: ellipsis;
}
.carousel--events .carousel__log-count {
margin-left: auto;
}
/* The newest line stands out; the older ones fade */
.carousel--events .carousel__log li:first-child {
color: var(--text, #e6e6ec);
}
.carousel--events .carousel__log li:nth-child(n + 4) {
opacity: 0.6;
}import Spill from "@bozdev/spill";
const root = document.querySelector(".carousel--events");
const prev = root.querySelector(".carousel__button--prev");
const next = root.querySelector(".carousel__button--next");
const log = root.querySelector(".carousel__log");
const api = Spill(root.querySelector(".carousel__viewport"), { align: "start" });
prev.addEventListener("click", () => api.scrollPrev());
next.addEventListener("click", () => api.scrollNext());
// What a line says about an event, read from the API as it fires
const details = {
select: (carousel) => `snap ${carousel.selectedScrollSnap()}`,
settle: (carousel) => `snap ${carousel.selectedScrollSnap()}`,
scroll: (carousel) => `${Math.round(carousel.scrollProgress() * 100)}%`,
slidesInView: (carousel) => `[${carousel.slidesInView().join(", ")}]`,
};
const span = (part, text = "") => {
const element = document.createElement("span");
element.className = `carousel__log-${part}`;
element.textContent = text;
return element;
};
// The log: newest first, six lines at most. The same event again (a scroll, frame after frame) counts up on its line.
let newest = null;
const write = (carousel, name) => {
const detail = details[name]?.(carousel) ?? "";
if (newest?.name === name) {
newest.count += 1;
newest.detail.textContent = detail;
newest.counter.textContent = `×${newest.count}`;
return;
}
const line = document.createElement("li");
newest = { name, count: 1, detail: span("detail", detail), counter: span("count") };
line.append(span("name", name), newest.detail, newest.counter);
log.prepend(line);
log.children[6]?.remove();
};
// Every event of the core. Each callback gets the API and the event's name.
const events = ["init", "reInit", "destroy", "select", "scroll", "settle", "resize", "slidesInView", "slidesChanged", "slideFocusStart", "slideFocus", "pointerDown", "pointerUp"];
for (const name of events) api.on(name, write);By attributes
No script of its own: numbered dots, a progress bar, Autoplay with a play button, and a next button outside the carousel.
<div class="carousel carousel--attributes">
<section id="attributes-demo" aria-label="Numbers"
data-spill-carousel='{"align":"start"}'
data-spill-plugins="autoplay"
data-spill-autoplay='{"delay":3000,"playOnInit":false}'>
<div class="carousel__viewport" data-spill-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>
</div>
<div class="carousel__progress" data-spill-progress aria-hidden="true"></div>
<div class="carousel__controls">
<div class="carousel__buttons">
<button class="carousel__button" type="button" aria-label="Previous slide" data-spill-prev>
<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" type="button" aria-label="Next slide" data-spill-next>
<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>
<button class="carousel__button carousel__button--play" type="button" aria-label="Autoplay" data-spill-play>
<svg class="icon-play" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M7 4.5v15a1 1 0 0 0 1.5.86l12-7.5a1 1 0 0 0 0-1.72l-12-7.5A1 1 0 0 0 7 4.5Z" /></svg>
<svg class="icon-pause" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><rect x="6" y="4" width="4" height="16" rx="1" /><rect x="14" y="4" width="4" height="16" rx="1" /></svg>
</button>
</div>
<div class="carousel__dots" data-spill-dots="number"></div>
</div>
</section>
<div class="carousel__elsewhere">
<span>Outside the carousel</span>
<button class="carousel__remote" type="button" data-spill-next data-spill-for="attributes-demo">
Next slide
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M5 12h14" /><path d="m12 5 7 7-7 7" /></svg>
</button>
</div>
</div>/* The progress bar: SpillAuto sets --spill-progress on it, 0 → 1 as the carousel scrolls */
.carousel--attributes .carousel__progress {
height: 0.25rem;
margin-top: 1.25rem;
overflow: hidden;
border-radius: 1rem;
background: var(--line, #24242a);
}
.carousel--attributes .carousel__progress::before {
content: "";
display: block;
height: 100%;
background: var(--accent, #9368f0);
transform: scaleX(var(--spill-progress, 0));
transform-origin: left;
}
/* Numbered dots (data-spill-dots="number"): the button holds its number */
.carousel--attributes .carousel__dots > button {
width: 1.75rem;
height: 1.75rem;
border-radius: 50%;
font: 600 0.8rem/1 var(--font-mono, monospace);
color: var(--muted, #a0a0aa);
}
.carousel--attributes .carousel__dots > button::after {
content: none;
}
.carousel--attributes .carousel__dots > button[aria-current="true"] {
color: var(--on-accent, #fff);
background: var(--accent, #9368f0);
}
/* The play button: aria-pressed says whether Autoplay runs */
.carousel--attributes .carousel__button--play .icon-pause,
.carousel--attributes .carousel__button--play[aria-pressed="true"] .icon-play {
display: none;
}
.carousel--attributes .carousel__button--play[aria-pressed="true"] .icon-pause {
display: block;
}
/* A control outside the carousel, tied to it by data-spill-for */
.carousel--attributes .carousel__elsewhere {
display: flex;
flex-wrap: wrap;
align-items: center;
justify-content: space-between;
gap: 0.75rem;
margin-top: 1.25rem;
padding-top: 1.25rem;
border-top: 1px dashed var(--line-strong, #34343c);
font-size: 0.9rem;
color: var(--muted, #a0a0aa);
}
.carousel--attributes .carousel__remote {
display: inline-flex;
align-items: center;
gap: 0.4rem;
padding: 0.55rem 0.95rem;
border: 0;
border-radius: 1.5rem;
font: inherit;
font-weight: 600;
color: var(--text, #e6e6ec);
background: none;
box-shadow: inset 0 0 0 1px var(--line-strong, #34343c);
cursor: pointer;
}
.carousel--attributes .carousel__remote[aria-disabled="true"] {
opacity: 0.35;
cursor: default;
}// That's all: every [data-spill-carousel] on the page builds itself and wires its controls — the one outside it too
import "@bozdev/spill/auto";Autoplay
The next slide every four seconds, a play / pause button that shows what autoplay is doing, and a line that fills until the next move.
<div class="carousel carousel--autoplay">
<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">
<button class="carousel__button carousel__button--play" type="button" aria-label="Autoplay" aria-pressed="false">
<svg class="icon-pause" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><rect x="6" y="4" width="4" height="16" rx="1" /><rect x="14" y="4" width="4" height="16" rx="1" /></svg>
<svg class="icon-play" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M7 4.5v15a1 1 0 0 0 1.5.86l12-7.5a1 1 0 0 0 0-1.72l-12-7.5A1 1 0 0 0 7 4.5Z" /></svg>
</button>
<div class="carousel__timer" aria-hidden="true"><div class="carousel__timer-fill"></div></div>
<div class="carousel__dots"></div>
</div>
</div>/* The play / pause button shows one icon at a time: pause while autoplay plays (aria-pressed="true"), play while it
doesn't */
.carousel--autoplay .carousel__button--play {
flex: none;
}
.carousel--autoplay .carousel__button--play[aria-pressed="true"] .icon-play,
.carousel--autoplay .carousel__button--play:not([aria-pressed="true"]) .icon-pause {
display: none;
}
/* The time to the next slide: a thin line the script fills while the timer counts */
.carousel--autoplay .carousel__timer {
flex: 1;
min-width: 2rem;
height: 2px;
border-radius: 1px;
overflow: hidden;
background: var(--line-strong, #34343c);
}
.carousel--autoplay .carousel__timer-fill {
height: 100%;
background: var(--accent, #9368f0);
transform: scaleX(0);
transform-origin: left;
}
/* Reduced motion: no moving line (Spill's own moves jump then, autoplay's included) */
@media (prefers-reduced-motion: reduce) {
.carousel--autoplay .carousel__timer {
visibility: hidden;
}
}import Spill from "@bozdev/spill";
import Autoplay from "@bozdev/spill/plugins/autoplay";
const root = document.querySelector(".carousel--autoplay");
const play = root.querySelector(".carousel__button--play");
const fill = root.querySelector(".carousel__timer-fill");
const dots = root.querySelector(".carousel__dots");
const api = Spill(root.querySelector(".carousel__viewport"), { align: "start" }, [Autoplay({ delay: 4000 })]);
const autoplay = api.plugins().autoplay;
// Play / pause. The button shows the state, whatever changed it: a click here, a drag or a focus in the carousel
play.addEventListener("click", () => (autoplay.isPlaying() ? autoplay.stop() : autoplay.play()));
const showState = () => play.setAttribute("aria-pressed", String(autoplay.isPlaying()));
// The line fills while the timer counts down to the next slide, and empties when the timer stops
let filling = null;
const startFill = () => {
filling?.cancel();
const ms = autoplay.timeUntilNext();
if (ms !== null) filling = fill.animate({ transform: ["scaleX(0)", "scaleX(1)"] }, { duration: ms, easing: "linear" });
};
const stopFill = () => filling?.cancel();
// 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();
showState();
};
api
.on("init", () => {
refresh();
startFill(); // autoplay started while the carousel was built, before these listeners
})
.on("reInit", refresh)
.on("select", selectDot)
.on("autoplay:play", showState)
.on("autoplay:stop", showState)
.on("autoplay:timerset", startFill)
.on("autoplay:timerstopped", stopFill);Class names
ClassNames marks the selected snap's slide, and the CSS lets the others step back — only once the class is there, so nothing is dimmed without JavaScript.
<div class="carousel carousel--class-names">
<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>.carousel--class-names {
--slide-size: 60%;
}
/* ClassNames puts is-snapped on the selected snap's slide; the others step back. The rule waits for the class, so
before JavaScript (and without it) every slide looks the same. The card scales, not the slide: Spill measures the
slides where they're drawn */
.carousel--class-names .carousel__card {
transition:
opacity 0.3s,
scale 0.3s;
}
.carousel--class-names .carousel__container:has(.is-snapped) .carousel__slide:not(.is-snapped) .carousel__card {
opacity: 0.4;
scale: 0.88;
}
@media (prefers-reduced-motion: reduce) {
.carousel--class-names .carousel__card {
transition: none;
}
}import Spill from "@bozdev/spill";
import ClassNames from "@bozdev/spill/plugins/class-names";
const root = document.querySelector(".carousel--class-names");
const prev = root.querySelector(".carousel__button--prev");
const next = root.querySelector(".carousel__button--next");
const dots = root.querySelector(".carousel__dots");
// Every snap centered (containScroll: false leaves room at the ends); ClassNames marks the selected one's slide
const api = Spill(root.querySelector(".carousel__viewport"), { align: "center", containScroll: false }, [ClassNames()]);
// 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();
});Auto height
Slides of different heights: the carousel is as tall as the selected one and follows it, smoothly unless you ask for reduced motion.
<div class="carousel carousel--auto-height">
<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>.carousel--auto-height {
--slide-size: 100%;
}
/* AutoHeight writes the selected slide's height on the container. The slides keep their own heights (not the row's),
and the height changes smoothly */
.carousel--auto-height .carousel__container {
align-items: flex-start;
transition: height 0.3s ease;
}
/* Slides of different heights */
.carousel--auto-height .carousel__slide:nth-child(2) {
--slide-height: 18rem;
}
.carousel--auto-height .carousel__slide:nth-child(3) {
--slide-height: 9rem;
}
.carousel--auto-height .carousel__slide:nth-child(4) {
--slide-height: 22rem;
}
.carousel--auto-height .carousel__slide:nth-child(5) {
--slide-height: 11rem;
}
@media (prefers-reduced-motion: reduce) {
.carousel--auto-height .carousel__container {
transition: none;
}
}import Spill from "@bozdev/spill";
import AutoHeight from "@bozdev/spill/plugins/auto-height";
const root = document.querySelector(".carousel--auto-height");
const prev = root.querySelector(".carousel__button--prev");
const next = root.querySelector(".carousel__button--next");
const dots = root.querySelector(".carousel__dots");
// AutoHeight sets the container's height to the selected slide's; the CSS makes the change smooth
const api = Spill(root.querySelector(".carousel__viewport"), { align: "start" }, [AutoHeight()]);
// 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();
});Thumbnails
Two carousels: a thumbnail's click scrolls the main one there, and the main one's select marks its thumbnail and brings it into view.
<div class="carousel carousel--thumbnails">
<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 class="carousel__slide"><div class="carousel__card">9</div></div>
<div class="carousel__slide"><div class="carousel__card">10</div></div>
</div>
</div>
<div class="carousel__viewport carousel__thumbs">
<div class="carousel__container">
<button class="carousel__slide carousel__thumb" type="button" aria-label="Go to slide 1"><span class="carousel__card">1</span></button>
<button class="carousel__slide carousel__thumb" type="button" aria-label="Go to slide 2"><span class="carousel__card">2</span></button>
<button class="carousel__slide carousel__thumb" type="button" aria-label="Go to slide 3"><span class="carousel__card">3</span></button>
<button class="carousel__slide carousel__thumb" type="button" aria-label="Go to slide 4"><span class="carousel__card">4</span></button>
<button class="carousel__slide carousel__thumb" type="button" aria-label="Go to slide 5"><span class="carousel__card">5</span></button>
<button class="carousel__slide carousel__thumb" type="button" aria-label="Go to slide 6"><span class="carousel__card">6</span></button>
<button class="carousel__slide carousel__thumb" type="button" aria-label="Go to slide 7"><span class="carousel__card">7</span></button>
<button class="carousel__slide carousel__thumb" type="button" aria-label="Go to slide 8"><span class="carousel__card">8</span></button>
<button class="carousel__slide carousel__thumb" type="button" aria-label="Go to slide 9"><span class="carousel__card">9</span></button>
<button class="carousel__slide carousel__thumb" type="button" aria-label="Go to slide 10"><span class="carousel__card">10</span></button>
</div>
</div>
</div>/* The row of thumbnails: a second carousel, its slides small buttons (the cards' colors come along) */
.carousel--thumbnails .carousel__thumbs {
--slide-size: 5.5rem;
--slide-spacing: 0.5rem;
--slide-height: 4rem;
margin-top: 0.75rem;
}
.carousel--thumbnails .carousel__thumb {
padding: 0;
border: 0;
border-radius: 0.75rem;
background: none;
opacity: 0.45;
cursor: pointer;
transition: opacity 0.2s;
}
.carousel--thumbnails .carousel__thumb:hover {
opacity: 0.75;
}
.carousel--thumbnails .carousel__thumb[aria-current="true"] {
opacity: 1;
}
/* The focus ring inside: the row clips what's outside it */
.carousel--thumbnails .carousel__thumb:focus-visible {
outline-offset: -2px;
}
.carousel--thumbnails .carousel__thumb .carousel__card {
border-radius: inherit;
font-size: 1.25rem;
}
@media (prefers-reduced-motion: reduce) {
.carousel--thumbnails .carousel__thumb {
transition: none;
}
}import Spill from "@bozdev/spill";
const root = document.querySelector(".carousel--thumbnails");
// Two carousels: the main one (the first viewport), and the thumbnails, gliding freely with a snap for each
const main = Spill(root.querySelector(".carousel__viewport"));
const thumbs = Spill(root.querySelector(".carousel__thumbs"), { containScroll: "keepSnaps", dragFree: true });
// A thumbnail's click: the main carousel goes to its slide (a snap a slide here, so the indexes match)
thumbs.slideNodes().forEach((thumb, index) => thumb.addEventListener("click", () => main.scrollTo(index)));
// The main carousel's select: its thumbnail marked, and the row scrolled to bring it into view
const sync = () => {
const selected = main.selectedScrollSnap();
thumbs.slideNodes().forEach((thumb, index) => thumb.setAttribute("aria-current", String(index === selected)));
thumbs.scrollTo(selected);
};
main.on("init", sync).on("select", sync);Scale
The slide in the middle at full size, the others smaller as they move away — a CSS scroll-driven animation, with no script for it.
<div class="carousel carousel--scale">
<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>
</div>
</div>/* Narrower slides: more of the smaller ones shows */
.carousel--scale {
--slide-size: 60%;
}
/* The viewport really scrolls, so CSS alone can follow it: a scroll-driven animation. view(inline) is the card's way
across the viewport — 0% as it comes in at one edge, 50% in the middle, 100% as it leaves at the other — and the
card scales along it. The card, not the slide: Spill measures the slides where they're drawn. Without support, or
with reduced motion, every card simply stays full size. */
@supports (animation-timeline: view()) {
@media (prefers-reduced-motion: no-preference) {
.carousel--scale .carousel__card {
animation: carousel-scale linear both;
animation-timeline: view(inline);
}
@keyframes carousel-scale {
0%,
100% {
scale: 0.75;
}
50% {
scale: 1;
}
}
}
}import Spill from "@bozdev/spill";
const root = document.querySelector(".carousel--scale");
// The scale is all CSS (style.css): the script only builds the carousel. Every slide can sit in the middle (the
// default align, "center"), the first and the last too: containScroll false leaves room before and after them.
// It starts on the second slide, with a smaller one on each side.
Spill(root.querySelector(".carousel__viewport"), { containScroll: false, startIndex: 1 });Opacity
The slides fade as they leave the middle, worked out on every scroll event from scrollSnapList() and scrollProgress() — Embla's tween way.
<div class="carousel carousel--opacity">
<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>
</div>
</div>import Spill from "@bozdev/spill";
const root = document.querySelector(".carousel--opacity");
// Every slide can sit in the middle (the default align, "center"), the first and the last too: containScroll false
// leaves room before and after them. It starts on the second slide, with a faded one on each side.
const api = Spill(root.querySelector(".carousel__viewport"), { containScroll: false, startIndex: 1 });
// The faintest a slide gets: never invisible, so the next ones still show they're there. Opacity moves nothing,
// so it stays with prefers-reduced-motion: reduce (Spill's own moves jump there by themselves).
const MIN_OPACITY = 0.35;
// Embla's tween: each slide's opacity from how far its snap is from the scroll. scrollSnapList() and
// scrollProgress() both run 0 to 1 across the carousel; the distance is counted in the way to the next snap on
// the scroll's side: 0 with the slide in place, 1 once the scroll reaches that next snap.
const tween = () => {
const snaps = api.scrollSnapList();
const progress = api.scrollProgress();
const slides = api.slideNodes(); // one slide a snap here (several a snap: api.internalEngine().slideRegistry)
snaps.forEach((snap, index) => {
const next = snaps[progress < snap ? index - 1 : index + 1] ?? snap;
const distance = Math.min(1, Math.abs(snap - progress) / (Math.abs(next - snap) || 1));
slides[index].style.opacity = (1 - distance * (1 - MIN_OPACITY)).toFixed(3);
});
};
// Every frame it scrolls, and when it's built or measured again
api.on("init", tween).on("reInit", tween).on("scroll", tween);