Class names
ClassNames puts classes on the slides and the viewport as the carousel's state changes — the selected snap, the slides in view, a drag — for your CSS to style.
Class names
<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();
});ClassNames has embla-carousel-class-names’ options, by the same names. It only adds and removes classes; the look is your CSS.
Add it
import Spill from "@bozdev/spill";
import ClassNames from "@bozdev/spill/plugins/class-names";
const api = Spill(viewport, { align: "center" }, [ClassNames()]);
It is also a named export of the package, import { ClassNames } from "@bozdev/spill", and Spill.ClassNames with a <script> tag. By attributes, it is class-names, its options in data-spill-class-names:
<div data-spill-carousel data-spill-plugins="class-names" data-spill-class-names='{"snapped":"is-active"}'>
…
</div>
In api.plugins() it is classNames.
Options
| Option | Default | |
|---|---|---|
active |
true |
false: no classes |
breakpoints |
{} |
Options by media query, merged in while it matches (Breakpoints) |
snapped |
"is-snapped" |
On the selected snap’s slides |
inView |
"is-in-view" |
On the slides in view |
draggable |
"is-draggable" |
On the viewport, when a mouse can drag it |
dragging |
"is-dragging" |
On the viewport, while it is pressed |
Each class is a string — several separated by spaces — or an array. An empty string writes none:
ClassNames({
snapped: "is-active",
inView: ["is-visible", "is-seen"],
dragging: "", // no class for this one
});
ClassNames.globalOptions holds options every ClassNames starts from, under its own — as Spill.globalOptions does for the carousel.
Which element, and when
| Option | On | When |
|---|---|---|
snapped |
Each slide of the selected snap — one, or several with slidesToScroll or at a trimmed edge |
When the carousel is built, then on every select and reInit (a new size can regroup the snaps). Under a finger it moves as soon as another snap is nearest, before the scroll comes to rest |
inView |
Each slide in view: any part of it, or as much as inViewThreshold asks |
On every slidesInView — the first one a moment after the carousel is built |
draggable |
The viewport | When the carousel is built, if watchDrag isn’t false |
dragging |
The viewport | From pointerDown to pointerUp: any press — a mouse’s, a finger’s, a pen’s — a click included. A finger’s press ends as the browser takes it over to scroll |
destroy() takes every class away. A rebuild does too — api.reInit(), a breakpoint, slides added or removed — and then writes them again with the options in force.
The viewport carries two attributes of the core’s own, without the plugin: data-spill-draggable (the same as is-draggable) and data-spill-dragging — the latter only while a mouse really drags, past dragThreshold, not on a plain click.
CSS recipes
The selected slide
Let the other slides step back — only once ClassNames has marked one, so without JavaScript every slide looks the same. :has() waits for the class:
.slide > * {
transition: opacity 0.3s, scale 0.3s;
}
.container:has(.is-snapped) .slide:not(.is-snapped) > * {
opacity: 0.4;
scale: 0.9;
}
@media (prefers-reduced-motion: reduce) {
.slide > * {
transition: none;
}
}
Scale what's in the slide
Spill measures the slides where they are drawn. A scale or a transform on a slide throws its snap off the next time the carousel measures — put it on the slide’s content, as here.
The slides in view
With inViewThreshold, “in view” can mean “nearly all of it shows”. Fade the slides the edges cut:
Spill(viewport, { align: "start", inViewThreshold: 0.9 }, [ClassNames()]);
.slide {
transition: opacity 0.3s;
}
.container:has(.is-in-view) .slide:not(.is-in-view) {
opacity: 0.35;
}
A grab cursor
.viewport.is-draggable {
cursor: grab;
}
.viewport.is-dragging {
cursor: grabbing;
}
Without the plugin, the core’s attributes do the same: .viewport[data-spill-draggable] and .viewport[data-spill-dragging].
Breakpoints
active: false leaves the classes out. In breakpoints, that goes by the screen — a carousel on a phone, a plain grid on a wide screen with no slide dimmed:
Spill(viewport, { align: "start" }, [
ClassNames({ breakpoints: { "(min-width: 1024px)": { active: false } } }),
]);
A breakpoint that starts or stops matching rebuilds the carousel: the classes are taken away, then written again with the options in force. CSS that waits for a class, as in the recipes above, then simply doesn’t apply.
When the carousel itself is off (its own active: false), so is ClassNames. More on screens: Breakpoints.