By attributes
Write the markup and the carousel builds itself — its options, plugins and controls in attributes, the controls anywhere on the page.
SpillAuto builds carousels from attributes: no script per carousel, and a carousel’s controls can be anywhere on the page. The one below has no script of its own — its numbered dots, its progress bar, its play button for Autoplay and the next button outside it are all in the markup.
By attributes
<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";Start it
One import, and every [data-spill-carousel] on the page builds itself:
import "@bozdev/spill/auto";
Or, without a bundler, one tag:
<script src="https://cdn.jsdelivr.net/npm/@bozdev/spill@0.1.0/dist/spill.auto.js"></script>
Both register the three plugins — Autoplay, ClassNames and AutoHeight — and call SpillAuto.start(). To load only what you use, start it yourself:
import { SpillAuto } from "@bozdev/spill/attributes";
import Autoplay from "@bozdev/spill/plugins/autoplay";
SpillAuto.plugins = { autoplay: Autoplay };
SpillAuto.start();
The markup
The carousel element holds the options, the plugins and their options. Inside it, a viewport and the controls; a control elsewhere names the carousel’s id.
<section id="gallery" aria-label="Gallery"
data-spill-carousel='{"align":"start"}'
data-spill-plugins="autoplay"
data-spill-autoplay='{"delay":5000}'>
<div class="viewport" data-spill-viewport>
<div class="container">
<div class="slide">…</div>
<div class="slide">…</div>
<div class="slide">…</div>
</div>
</div>
<button type="button" data-spill-prev>Previous</button>
<button type="button" data-spill-next>Next</button>
<button type="button" data-spill-play>Autoplay</button>
<div data-spill-dots></div>
<div data-spill-progress></div>
</section>
<!-- Anywhere else on the page -->
<button type="button" data-spill-next data-spill-for="gallery">Next slide</button>
The JSON goes in single quotes, so its own double quotes fit. JSON that doesn’t parse gets a warning in the console, and the defaults are used instead. The viewport, its container and its slides are as in the markup for Spill(); the look is your CSS.
Every attribute
| Attribute | On | What it does |
|---|---|---|
data-spill-carousel |
The carousel | Builds it. Its value: the options as JSON ('{"align":"start"}'); empty, the defaults |
data-spill-viewport |
An element inside | The box that scrolls. None marked: the carousel element is the viewport itself — mark one when the controls are inside |
data-spill-plugins |
The carousel | Plugins by name, separated by spaces or commas: "autoplay class-names auto-height" |
data-spill-<name> |
The carousel | A plugin’s options as JSON, by its name in data-spill-plugins: data-spill-autoplay='{"delay":3000}' |
data-spill-prev, data-spill-next |
A button | The previous or next snap. At an edge, aria-disabled="true" and data-spill-disabled, and its clicks are ignored — a focused button keeps its focus |
data-spill-dots |
A box | Filled with a button for each snap, aria-current="true" on the selected one. data-spill-dots="number": each holds its number |
data-spill-progress |
Any element | Its --spill-progress goes from 0 to 1 as the carousel scrolls |
data-spill-to="3" |
A button | The 3rd snap (counted from 1) |
data-spill-play |
A button | Autoplay on or off; aria-pressed says which |
data-spill-for="<id>" |
A control | Its carousel, by the carousel’s id — for a control outside it |
data-spill-aria="false" |
The carousel | No roles or labels on the carousel and its slides |
A control belongs to the carousel it’s in — the nearest one, when carousels are nested — or to the one its data-spill-for names. Controls are found when the carousel is built: one added to the page later isn’t wired.
The progress is a CSS variable, so the bar is yours to draw:
.progress { height: 0.25rem; overflow: hidden; background: #ddd; }
.progress::before {
content: "";
display: block;
height: 100%;
background: rebeccapurple;
transform: scaleX(var(--spill-progress, 0));
transform-origin: left;
}
Plugins by name
data-spill-plugins names plugins from SpillAuto.plugins. @bozdev/spill/auto and spill.auto.js register these three:
| Name | Plugin | Its options attribute |
|---|---|---|
autoplay |
Autoplay | data-spill-autoplay='{"delay":4000,"stopOnMouseEnter":true}' |
class-names |
Class names | data-spill-class-names='{"snapped":"is-active"}' |
auto-height |
Auto height | data-spill-auto-height='{"breakpoints":{"(min-width: 768px)":{"active":false}}}' |
A name that isn’t registered gets a warning in the console, and the carousel is built without it. Your own plugin is named the same way — register it before start():
import { SpillAuto } from "@bozdev/spill/attributes";
import Autoplay from "@bozdev/spill/plugins/autoplay";
import Logger from "./logger.js";
SpillAuto.plugins = { autoplay: Autoplay, logger: Logger };
SpillAuto.start();
data-spill-plugins="autoplay logger" then calls Logger() with the JSON in data-spill-logger (or {}).
The name in the attribute is the registered one. api.plugins() lists them by each plugin’s own name: class-names is api.plugins().classNames, auto-height is api.plugins().autoHeight.
Options that are functions — align as a function, a per-snap delay, the watch… callbacks — can’t be written in JSON. Build that carousel with Spill() instead.
Words
SpillAuto writes labels for screen readers. SpillAuto.words holds them, to put in a site’s language:
import { SpillAuto } from "@bozdev/spill/attributes";
import Autoplay from "@bozdev/spill/plugins/autoplay";
SpillAuto.words = {
carousel: "Karussell",
carouselRole: "Karussell",
slideRole: "Folie",
slide: "{0} von {1}",
prev: "Vorherige Folie",
next: "Nächste Folie",
goTo: "Gehe zu Folie {0}",
autoplay: "Automatische Wiedergabe",
};
SpillAuto.plugins = { autoplay: Autoplay };
SpillAuto.start();
| Word | Default | Where |
|---|---|---|
carousel |
"Carousel" |
The carousel’s aria-label, when it has none |
carouselRole |
"carousel" |
The carousel’s aria-roledescription |
slideRole |
"slide" |
Each slide’s aria-roledescription |
slide |
"{0} of {1}" |
Each slide’s aria-label: its number, and how many there are |
prev |
"Previous slide" |
A previous button’s aria-label |
next |
"Next slide" |
A next button’s aria-label |
goTo |
"Go to slide {0}" |
Each dot’s aria-label: its snap’s number |
autoplay |
"Autoplay" |
A play button’s aria-label |
The words are read when a carousel is built: set them before start(). To change only a few, set only those — SpillAuto.words = { next: "Weiter" } — and the words you leave out stay English.
With @bozdev/spill/auto
The auto import builds the page’s carousels as soon as it runs, and imports run before the code next to them. Set the words in a module of their own, imported before it.
// words.js
import { SpillAuto } from "@bozdev/spill/attributes";
SpillAuto.words = { prev: "Vorherige Folie", next: "Nächste Folie" };
// main.js — the words first, then the carousels
import "./words.js";
import "@bozdev/spill/auto";
With the <script> tag, load spill.global.js instead of spill.auto.js and start it yourself:
<script src="https://cdn.jsdelivr.net/npm/@bozdev/spill@0.1.0/dist/spill.global.js"></script>
<script>
Spill.SpillAuto.words = { next: "Weiter" };
Spill.SpillAuto.plugins = { autoplay: Spill.Autoplay };
Spill.SpillAuto.start();
</script>
What it writes for screen readers
| Where | What |
|---|---|
| The carousel | role="region", aria-roledescription="carousel", and aria-label="Carousel" when it has neither an aria-label nor an aria-labelledby |
| Each slide | role="group", aria-roledescription="slide", aria-label="1 of 5" |
| Previous, next, play | An aria-label each, when it has none |
| Previous, next | aria-disabled="true" at an edge, "false" otherwise |
| Play | aria-pressed="true" while Autoplay runs, "false" otherwise |
| Each dot | aria-label="Go to slide 2"; aria-current="true" on the selected one |
The words are from SpillAuto.words. Your own attributes stay — give the carousel an aria-label that says what it shows. A data-spill-to button gets no label: give it text. data-spill-aria="false" leaves the carousel and its slides as they are; the controls still get theirs.
When a carousel is taken down, what SpillAuto wrote goes with it: the labels, the dots, the controls’ states. Your own data-spill-viewport stays, so a later scan() builds the same carousel again.
The SpillAuto API
SpillAuto.plugins |
{ name: factory } — the plugins data-spill-plugins can name |
SpillAuto.words |
The labels it writes (Words) |
SpillAuto.start({ observe = true }) |
Builds every carousel on the page — once the document is parsed. observe: then watches the page, builds the carousels added later and takes down the ones removed |
SpillAuto.stop() |
Takes every carousel down and stops watching |
SpillAuto.scan(roots?) |
Builds the carousels in these elements (the elements too; the whole document by default). Each carousel is built once |
SpillAuto.forget(roots) |
Takes down the carousels in these elements (the elements too) |
SpillAuto.get(element) |
A carousel’s API, by its element or anything in it; null when there’s none |
SpillAuto.all() |
Every carousel built: a Map of element to API |
scan and forget take an array: SpillAuto.scan([document.querySelector("main")]). With the API, the carousel is yours to drive:
const api = SpillAuto.get(document.querySelector("#gallery"));
api?.scrollTo(2);
The spill:ready event
Each carousel built fires spill:ready on its element. It bubbles, and event.detail.api is its API:
import { SpillAuto } from "@bozdev/spill/attributes";
document.addEventListener("spill:ready", (event) => {
const { api } = event.detail;
api.on("select", () => console.log(event.target.id, api.selectedScrollSnap()));
});
SpillAuto.start();
Listen before the carousels are built — before start(), or, with @bozdev/spill/auto, in a module imported before it. The ones built already are in SpillAuto.all(). The carousel’s own init comes after spill:ready, so a listener added there still hears it.
Routers
start() watches the page, so carousels a script adds later build themselves, and the ones it removes are taken down. A site that swaps its content with a client-side router can say when instead: start without watching, take the old content’s carousels down before it goes, and build the new content’s once it’s in.
SpillAuto.start({ observe: false });
// In your router's hooks — their names vary
router.beforeSwap(() => SpillAuto.forget([document.querySelector("main")]));
router.afterSwap(() => SpillAuto.scan([document.querySelector("main")]));
Take them down before a router keeps a copy of the page for the back button, too: the inline styles, the labels and the dots go, and a copy that comes back is built fresh. Frameworks has Astro’s view transitions as an example.