Options
Every option a carousel takes — its type, its default, and what it changes.
Options are the second argument of Spill(). They have Embla’s names and defaults (there is no loop), and you only pass the ones you change:
import Spill from "@bozdev/spill";
const api = Spill(document.querySelector(".viewport"), { align: "start", slidesToScroll: "auto" });
| Option | Default | |
|---|---|---|
container |
null |
The slides’ parent |
slides |
null |
The slides |
axis |
"x" |
A row or a column |
direction |
"ltr" |
Left to right or right to left |
align |
"center" |
Where a snap sits in the viewport |
slidesToScroll |
1 |
How many slides make a snap |
containScroll |
"trimSnaps" |
What happens to snaps at the edges |
startIndex |
0 |
The snap it starts on |
duration |
25 |
How long a programmatic move takes |
dragFree |
false |
No snapping |
dragThreshold |
10 |
How far a mouse moves before it drags |
skipSnaps |
false |
A throw can pass several snaps |
active |
true |
On or off |
breakpoints |
{} |
Options for media queries |
inViewThreshold |
0 |
How much of a slide shows to count as in view |
watchDrag |
true |
Mouse dragging, and scrolling by hand |
watchResize |
true |
Measured again after a size changes |
watchSlides |
true |
Rebuilt when slides come or go |
watchFocus |
true |
A focus in a slide brings its snap |
Layout
container
Type string | HTMLElement | null · Default null
The slides’ parent. A selector is looked up inside the viewport (the first match, at any depth); an element is used as it is. null — or a selector that finds nothing — takes the viewport’s first child. With no container at all, Spill stays off.
Spill(viewport, { container: ".track" });
slides
Type string | HTMLElement[] | NodeList | null · Default null
The slides. A selector is looked up inside the container, at any depth; an array or a NodeList is used as it is. null takes the container’s children. A rebuild looks a selector up again, while elements you gave stay the ones you gave — pass new ones with api.reInit({ slides }).
Spill(viewport, { slides: ".slide" });
axis
Type "x" | "y" · Default "x"
"x" is a row, scrolled sideways. "y" is a column: give the viewport a height and the container flex-direction: column, and Spill scrolls it up and down (overflow-y, a y snap type, data-spill-axis="y" on the viewport). See the vertical example.
Spill(viewport, { axis: "y" });
direction
Type "ltr" | "rtl" · Default "ltr"
"rtl" is a right-to-left row: the first slide on the right, the next ones to its left. Set dir="rtl" on the viewport or an ancestor as well — the browser lays the row out, Spill reads it; you need both. It applies to axis: "x" only. See the right-to-left example.
Spill(viewport, { direction: "rtl" });
align
Type "start" | "center" | "end" | function · Default "center"
Where a snap sits in the viewport: its start at the viewport’s start, in the middle, or its end at the viewport’s end. A snap is a slide — or a group of them, with slidesToScroll. In a right-to-left row, the start is the right edge.
Align
<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);The scroll can’t go before its start or past its end, so near the edges a snap can’t always take its place: the first snap sits at the start whatever the align, and the last at the end. containScroll: false adds room so that every snap can.
A function places each snap yourself. It gets the viewport’s size (clientWidth, or clientHeight with axis: "y"), the snap’s size (from its first slide’s start to its last slide’s end) and the snap’s index, and returns how far from the viewport’s start the snap’s start sits, in pixels. "start" is 0, "center" is (viewSize - snapSize) / 2, "end" is viewSize - snapSize.
// Every snap a tenth of the way in
Spill(viewport, { align: (viewSize, snapSize, index) => viewSize * 0.1 });
slidesToScroll
Type number | "auto" · Default 1
How many slides make one snap — what one scrollNext(), one dot or one throw moves. A number groups that many slides in order (the last group can hold fewer). "auto" groups as many as fit in the viewport, measured; when your CSS changes the slides’ sizes, the groups follow. Spill reads the sizes and never sets them: how many slides show is up to your CSS.
Spill(viewport, { slidesToScroll: 2 });
Spill(viewport, { slidesToScroll: "auto" });
Slides to scroll
<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();
});containScroll
Type "trimSnaps" | "keepSnaps" | false · Default "trimSnaps"
The scroll stops at its two ends, so near them several snaps can come out at the same place.
"trimSnaps"makes those one snap, holding all their slides: no step that doesn’t move."keepSnaps"keeps every snap, even where several sit at the same place — the selection then moves while the scroll stays.falsegives the row room at both ends, so that every snap takes its place — the first slide centered withalign: "center". The room is the container’s::beforeand::after: two empty flex items, from one constructed stylesheet Spill adds (no file, no<style>, nothing a Content Security Policy blocks), shaped by adata-spill-roomattribute and the--spill-room-start,--spill-room-endand--spill-room-gapcustom properties Spill sets on the container. Slides sized in%keep their size. Leave the container’s::beforeand::afterto Spill. In a browser without constructed stylesheets, Spill pads the container instead.destroy()takes it all away.
Spill(viewport, { align: "center", containScroll: false });
Scrolling
startIndex
Type number · Default 0
The snap it starts on (rounded, and held within the snaps), placed at once without an animation. Given to reInit(), it’s where the rebuilt carousel starts; without it, a rebuild keeps the selected snap.
Spill(viewport, { startIndex: 2 });
duration
Type number · Default 25
How long a programmatic move takes — scrollTo(), scrollNext(), scrollPrev(), a mouse’s release, a focus — in steps of 16 ms (25 is about 400 ms), eased out. 20 to 60 is the useful range: higher is slower. 0 jumps. With prefers-reduced-motion: reduce, every move jumps. A finger’s or a trackpad’s scroll is the browser’s own and doesn’t use it.
Spill(viewport, { duration: 40 }); // about 640 ms
dragFree
Type boolean · Default false
No snapping: the viewport gets scroll-snap-type: none and data-spill-free. A throw — a finger’s, or a mouse’s, which carries its speed on for a moment — glides and rests wherever it ends. The snaps are still there for the API: scrollTo() and the buttons go to them, and the selected snap follows the nearest one as the row moves.
Spill(viewport, { dragFree: true });
Drag free
<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);dragThreshold
Type number · Default 10
How many pixels a pressed mouse moves before it drags. A shorter move is a click, so links and buttons in a slide still work; the click a real drag ends with is swallowed. A finger isn’t affected: its scroll is the browser’s.
Spill(viewport, { dragThreshold: 4 });
skipSnaps
Type boolean · Default false
false: a throw moves one snap at most. Under a finger, each snap’s first slide carries scroll-snap-stop: always; a mouse’s throw is held to the next snap. true: a strong throw can pass several snaps and stops at the one nearest where its momentum runs out.
Spill(viewport, { skipSnaps: true });
Skip snaps
<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();
});Behavior
active
Type boolean · Default true
false makes Spill step aside: it writes nothing, listens to nothing but its breakpoints, starts no plugins, and your CSS alone lays the slides out. The API is still there — its methods return empty values and the moves do nothing — and init still fires. It’s most useful in breakpoints: a carousel on a phone, a grid on a desktop.
Spill(viewport, { breakpoints: { "(min-width: 1024px)": { active: false } } });
breakpoints
Type object (a media query → options) · Default {}
Options for media queries. While a query matches, its options are merged over the others; when several match, they merge in the order written, so a later one wins. When a query starts or stops matching, the carousel is rebuilt: reInit fires, and the selected snap is kept. The breakpoints in Spill.globalOptions and in a plugin’s options are watched as well. More in Breakpoints.
Spill(viewport, {
align: "start",
breakpoints: {
"(min-width: 768px)": { slidesToScroll: 2 },
"(min-width: 1200px)": { active: false },
},
});
inViewThreshold
Type number | number[] · Default 0
How much of a slide has to show for it to count as in view — for slidesInView(), the slidesInView event and the ClassNames plugin’s is-in-view. 0 is any part of it, 0.5 half of it. It’s an IntersectionObserver’s threshold, measured against the viewport; with an array, its smallest value decides.
Spill(viewport, { inViewThreshold: 0.5 });
Watching
Each of these takes true (the default), false, or a function. A function is asked every time, with the API and what happened. Return true to let Spill do its part; return false — or nothing — and Spill skips it this time.
watchDrag
Type boolean | (api, event: PointerEvent) => boolean · Default true
true: a mouse drags the carousel — Spill’s own drag, since a finger and a trackpad scroll it natively anyway. A press in a form field (input, select, textarea, contenteditable) never drags.
false: no mouse drag, and no scrolling by hand at all — the viewport gets overflow: hidden, so a finger, a trackpad and the wheel don’t move it either. The API still does.
A function is asked on each press of a mouse’s main button on the viewport, with its pointerdown event; return true to drag. It isn’t asked for a finger or a pen — their scroll is the browser’s — and the viewport keeps overflow: auto and data-spill-draggable.
// No drag from a press on anything marked .no-drag
Spill(viewport, { watchDrag: (api, event) => !event.target.closest(".no-drag") });
watchResize
Type boolean | (api, entries: ResizeObserverEntry[]) => boolean · Default true
true: when the viewport or a slide changes size along the axis (by half a pixel or more), Spill measures again, puts the selected snap back in its place, and fires reInit, then resize. A carousel built while hidden — in a closed tab or a dialog — measures itself this way once it shows.
false: no ResizeObserver. After a change in size, call api.reInit() yourself.
A function gets the ResizeObserver’s entries — the viewport and the slides that changed, in either direction — before Spill looks at them; return true to let Spill go on (it still measures only when a size along the axis changed).
// Only the viewport's own size counts
Spill(viewport, { watchResize: (api, entries) => entries.some((entry) => entry.target === api.rootNode()) });
watchSlides
Type boolean | (api, mutations: MutationRecord[]) => boolean · Default true
true: when children are added to the container or removed from it, the carousel is rebuilt with its slides found again, and fires reInit, then slidesChanged. Only the container’s own children are watched, not deeper changes.
false: not watched. After changing the slides, call api.reInit().
A function gets the MutationObserver’s records; return true to rebuild.
// Rebuilt only when slides were added
Spill(viewport, { watchSlides: (api, mutations) => mutations.some((mutation) => mutation.addedNodes.length > 0) });
watchFocus
Type boolean | (api, event: FocusEvent) => boolean · Default true
true: when focus lands inside a slide — Tab to a link in it — Spill scrolls to that slide’s snap and fires slideFocusStart, then slideFocus.
false: Spill leaves it to the browser, which still brings the focused element into view (the viewport is a real scrolling box); the selected snap follows the scroll.
A function gets the focusin event; return true to scroll to the snap.
// A field in a slide: the browser's own scroll is enough
Spill(viewport, { watchFocus: (api, event) => !event.target.matches("input, textarea") });
Global options
Spill.globalOptions holds options every carousel starts from, under its own. It’s read whenever a carousel is built or rebuilt, so set it before building them; its breakpoints are watched too.
import Spill from "@bozdev/spill";
Spill.globalOptions = { align: "start", duration: 30 };
Each built-in plugin has its own: Autoplay.globalOptions, ClassNames.globalOptions, AutoHeight.globalOptions.
How options combine
The options in force are merged in this order, a later one winning: the defaults, Spill.globalOptions, the carousel’s own options, then its breakpoints that match. Plain objects merge key by key — breakpoints from the global options and from a carousel’s own combine — while anything else (an array, a function, an element) is replaced.
api.reInit(options)merges the new options into the ones given before: they add up from one call to the next.api.internalEngine().optionsreturns the options in force.defaultOptionsis exported, frozen:import { defaultOptions } from "@bozdev/spill".
By attributes
A carousel built by attributes takes its options as JSON in data-spill-carousel, so the function forms of align and the watch options, and elements for container and slides, aren’t available there — selectors are.