Markup and CSS
Three nested elements and your own stylesheet — your CSS lays the slides out, and Spill writes only what scrolling and snapping need.
Spill has no stylesheet. The slides’ sizes, the gaps, the colors and the controls are yours, as with Embla. Spill reads the layout your CSS makes, measures where each slide is drawn, and writes inline only what the browser needs to scroll and snap.
The markup
You give Spill the viewport: the box that scrolls. Its first element 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">1</div> <!-- the container's children (or options.slides) -->
<div class="slide">2</div>
<div class="slide">3</div>
</div>
</div>
import Spill from "@bozdev/spill";
const api = Spill(document.querySelector(".viewport"), { align: "start" });
The class names are yours, and so are the elements. A row of products or posts can be a real list: a <ul> as the container and <li> slides, with the list’s list-style, margin and padding reset in your CSS.
Another container, other slides
Two options change where Spill looks:
container— the slides’ parent: a selector, looked up inside the viewport, or an element.null, the default, is the viewport’s first element child.slides— a selector, looked up inside the container, or an array or a NodeList of elements.null, the default, is every child of the container.
Spill(viewport, {
container: ".track", // when it isn't the viewport's first child
slides: ".card", // only these are slides
});
Other elements in the container still take their room in the row; Spill just doesn’t snap to them. With watchSlides on (the default), adding or removing children of the container rebuilds the carousel.
What Spill writes
Everything Spill needs, it writes inline on your elements. destroy() takes all of it away again, and an element that had no style attribute before has none after. With active: false, Spill writes nothing at all.
Inline styles
| On | Property | Value |
|---|---|---|
| Viewport | overflow-x |
auto — hidden with watchDrag: false |
| Viewport | overflow-y |
hidden |
| Viewport | overscroll-behavior-x |
contain |
| Viewport | scrollbar-width |
none |
| Viewport | scroll-snap-type |
x mandatory — none with dragFree, and for as long as it animates or a mouse drags it |
| Viewport | user-select |
none, while a mouse drags it |
| Each snap’s first slide | scroll-snap-align |
start |
| Each snap’s first slide | scroll-margin-inline-start |
The snap’s alignment in px: how far from the viewport’s start the slide sits when its snap is selected |
| Each snap’s first slide | scroll-snap-stop |
always — not with skipSnaps |
| Container | --spill-room-start, --spill-room-end, --spill-room-gap |
With containScroll: false only: the room before the first snap and after the last, in px, and the container’s gap taken back (below) |
With axis: "y" the axes swap: overflow-y scrolls and overflow-x is hidden, and the rest become overscroll-behavior-y, y mandatory and scroll-margin-block-start.
Whatever align is, each snap is written as start plus a margin. That way the browser’s snap point is exactly the place Spill measured, and a finger or a trackpad stops where a button would.
Attributes
On the viewport, as hooks for your CSS:
| Attribute | When |
|---|---|
data-spill-viewport |
While the carousel is active. One you wrote yourself (as By attributes does) stays after destroy() |
data-spill-axis |
Always while active: "x" or "y" |
data-spill-draggable |
A mouse can drag it: watchDrag isn’t false (a function counts) |
data-spill-free |
dragFree: true |
data-spill-dragging |
While a mouse drags it, once it has moved dragThreshold px |
Where a browser doesn’t support scrollbar-width, Spill adds one rule once, [data-spill-viewport]::-webkit-scrollbar { display: none }, as a constructed stylesheet: no file, no <style> element, nothing a Content Security Policy blocks.
The plugins and the attributes layer write their own: Class names toggles classes such as is-snapped, Auto height sets the container’s height, and By attributes adds roles and labels.
Room for containScroll: false
With containScroll: false, every snap can take its place, the first and the last too, so the row may need room before the first slide or after the last. Spill makes it with the container’s ::before and ::after. It sets data-spill-room on the container ("x start end", say) and the custom properties above, and a constructed stylesheet, added once, turns the two into empty flex items of that size. Slides sized in % keep their size, and destroy() takes it all away. Leave the container’s ::before and ::after to Spill while it does this.
In a browser without constructed stylesheets, Spill pads the container instead (padding-inline-start and padding-inline-end, or padding-block-start and padding-block-end with axis: "y"). That works less well: slides sized in % shrink with the padding.
What your CSS does
The layout. A row is a flex container whose slides don’t grow or shrink:
.viewport {
overflow-x: auto; /* before JavaScript runs (and without it), the row still scrolls */
scrollbar-width: none;
}
.container {
display: flex;
gap: 1rem;
}
.slide {
flex: 0 0 80%; /* the slide's size */
min-width: 0; /* long content can't stretch it */
}
.viewport[data-spill-draggable] { cursor: grab; }
.viewport[data-spill-dragging] { cursor: grabbing; }
Inline styles win over your stylesheet’s rules for the same properties, so while the carousel is active, its overflow is Spill’s. With active: false Spill takes them away, and your CSS decides again.
Leave two things to Spill:
- Snapping. No
scroll-snap-type,scroll-snap-alignorscroll-paddingof your own. Spill writes the snap points from what it measures; ascroll-paddingor snap points on other slides would make the browser stop somewhere else. - Transforms on the slides. Spill measures each slide where it’s drawn, so a
transform,scaleortranslateon the container or a slide moves what it measures. Put an effect on the slide’s content instead.
Recipes
Slides per view
A slide’s flex-basis sets how many fit. Take the gaps out first: three slides with two 1rem gaps between them are each a third of what’s left.
.slide { flex: 0 0 100%; min-width: 0; } /* one on a phone */
@media (min-width: 640px) {
.slide { flex-basis: calc((100% - 1rem) / 2); } /* two */
}
@media (min-width: 1024px) {
.slide { flex-basis: calc((100% - 2 * 1rem) / 3); } /* three */
}
Spill reads the sizes and never sets them. To move a whole view at a time, set slidesToScroll: "auto": as many slides as fit in view make one snap, and it follows your CSS as the sizes change. Or set slidesToScroll for each media query with breakpoints.
Slides of different widths
Every slide can have its own size. Spill measures them one by one, and align places each snap: here "center", with the first and the last slide held to the edges by containScroll: "trimSnaps", the default.
Variable widths
<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();
});A slide can also take its width from its content, with flex: 0 0 auto. Give any image in it a width and a height, so the slide has its size before the image loads.
Gaps
gap on the container is all it takes. Spill measures where each slide is drawn, so the space between them is counted, and the slides need no padding of their own.
.container { display: flex; gap: 1.5rem; }
Peeking at the next slide
Make the slides narrower than the viewport, and the next one shows at the edge:
.slide { flex: 0 0 85%; min-width: 0; }
With align: "start", the next slide peeks in at the end. With "center", the default, both neighbors do. At the ends, containScroll: "trimSnaps" holds the first slide to the start and the last to the end. Set containScroll: false to center every slide, the first and the last too: Spill makes room before the first and after the last (Room for containScroll: false).
A grid inside a slide
A slide is yours, and any layout works inside it: a grid of cards, a figure with its caption, a form. Spill only scrolls the slides.
<div class="slide slide--grid">
<a href="/one/">…</a>
<a href="/two/">…</a>
<a href="/three/">…</a>
<a href="/four/">…</a>
</div>
.slide--grid {
display: grid;
grid-template-columns: repeat(2, minmax(0, 1fr));
gap: 0.75rem;
}
Tab moves through the links in order, and when the focus goes into a slide of another snap, Spill brings that snap in (watchFocus). A mouse press in a field — an input, a select, a textarea — never starts a drag.
A column
axis: "y" scrolls the viewport up and down. The column itself is your CSS: a height on the viewport, flex-direction: column on the container, and the slides’ sizes as shares of that height.
.viewport {
height: 22rem;
overflow-y: auto;
}
.container {
display: flex;
flex-direction: column;
gap: 1rem;
height: 100%; /* the slides' percentages need a height to share */
}
.slide { flex: 0 0 75%; min-height: 0; }
Spill(viewport, { axis: "y", align: "start" });
Vertical
<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();
});On a column, Spill writes overscroll-behavior-y: contain: a wheel or a finger over the carousel scrolls it, and at its ends the scroll stays there instead of moving on to the page. Keep a vertical carousel shorter than the screen, so there’s page around it to scroll by.
Right to left
Set direction: "rtl", and put dir="rtl" on the viewport or an ancestor. The two go together: dir lays the row out from the right, and direction tells Spill to read the scroll that way. With one and not the other, Spill measures from the wrong side.
<div class="carousel" dir="rtl">
<div class="viewport">…</div>
</div>
Spill(viewport, { align: "start", direction: "rtl" });
align: "start" is then the right edge. In a flex row, dir="rtl" also moves a previous button written first over to the right; mirror the arrow icons yourself.
Right to left
<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();
});Effects as it scrolls
The viewport really scrolls, so CSS scroll-driven animations can follow it without a script. animation-timeline: view(inline) runs an animation as an element crosses its scrolling box: 0% as it comes in at one edge, 50% in the middle, 100% as it leaves at the other.
@supports (animation-timeline: view()) {
@media (prefers-reduced-motion: no-preference) {
.slide > .card {
animation: card-focus linear both;
animation-timeline: view(inline);
}
@keyframes card-focus {
0%, 100% { opacity: 0.4; scale: 0.85; }
50% { opacity: 1; scale: 1; }
}
}
}
Animate what’s inside a slide, not the slide itself: Spill measures the slides where they’re drawn. In a column, use view(block). Where the browser has no support, or the user asks for reduced motion, the cards simply stay as they are. The Scale example works this way; Opacity does the same in JavaScript, on every scroll event.
Lazy images
loading="lazy" works as it does anywhere else: the browser decides when to fetch each image, with no script of yours or Spill’s.
<div class="slide">
<img src="photo-1.jpg" alt="…" width="1200" height="800">
</div>
<div class="slide">
<img src="photo-2.jpg" alt="…" width="1200" height="800" loading="lazy">
</div>
.slide img {
display: block;
width: 100%;
height: auto;
}
- Leave
loading="lazy"off the slides that show first. They’re needed at once. - Give each image a
widthand aheight(or anaspect-ratioin CSS), so its slide has its size before the image arrives. Spill measures again when a size along the axis changes, but the row would jump.