Methods

The carousel's API — what each method takes, what it returns, and what it does.

Spill() returns the carousel’s API: Embla’s methods, on a native scroll. Keep it — it’s how you move the carousel, read where it is, and listen to it.

import Spill from "@bozdev/spill";

const api = Spill(document.querySelector(".viewport"), { align: "start" });
const next = document.querySelector(".next");

next.addEventListener("click", () => api.scrollNext());
api.on("select", () => {
  next.disabled = !api.canScrollNext();
});
Method Returns
scrollNext(jump?) To the next snap
scrollPrev(jump?) To the previous snap
scrollTo(index, jump?) To a snap
canScrollNext() boolean Whether there’s a snap after the selected one
canScrollPrev() boolean Whether there’s a snap before it
selectedScrollSnap() number The selected snap
previousScrollSnap() number The snap selected before it
scrollSnapList() number[] Each snap’s place, 0 to 1
scrollProgress() number Where the scroll is, 0 to 1
slidesInView() number[] The slides in view
slidesNotInView() number[] The slides out of view
slideNodes() HTMLElement[] The slides
containerNode() HTMLElement or null The slides’ parent
rootNode() HTMLElement The viewport
plugins() object The plugins in force, by name
internalEngine() object What plugins need of the carousel
reInit(options?, plugins?) Rebuilt
destroy() Taken down
on(event, callback) the API Listen to an event
off(event, callback) the API Stop listening
emit(event) the API Fire an event

Moving

scrollNext

scrollNext(jump?: boolean): void

To the next snap. It animates over duration — or, with jump set to true, gets there at once. At the last snap it stays where it is.

api.scrollNext();
api.scrollNext(true); // no animation

scrollPrev

scrollPrev(jump?: boolean): void

To the previous snap, the same way. At the first snap it stays where it is.

scrollTo

scrollTo(index: number, jump?: boolean): void

To a snap, by its index from 0. The index is rounded and held within the snaps. If the snap changes, select fires at once, as the move starts; settle fires when it ends. With prefers-reduced-motion: reduce, a duration of 0 or jump, it gets there at once. While the carousel is inactive, it does nothing.

api.scrollTo(0);       // back to the first snap
api.scrollTo(3, true); // the fourth, at once

Where it is

canScrollNext

canScrollNext(): boolean

Whether there’s a snap after the selected one: false at the last snap, and while the carousel is inactive. A next button reads it on select and on reInit (see Buttons and dots).

canScrollPrev

canScrollPrev(): boolean

Whether there’s a snap before the selected one: false at the first snap, and while inactive.

selectedScrollSnap

selectedScrollSnap(): number

The selected snap’s index. It changes as a move starts — a button, scrollTo(), a mouse’s release — and, while a finger or a trackpad scrolls, whenever another snap is nearest.

api.on("select", () => {
  counter.textContent = `${api.selectedScrollSnap() + 1} / ${api.scrollSnapList().length}`;
});

previousScrollSnap

previousScrollSnap(): number

The snap that was selected before the current one — to tell which way a move went, or to undo a style on the slide it left.

scrollSnapList

scrollSnapList(): number[]

Each snap’s place along the scroll, from 0 (the start) to 1 (the end). Its length is the number of snaps: one dot each.

dots.replaceChildren(...api.scrollSnapList().map((_, index) => makeDot(index)));

scrollProgress

scrollProgress(): number

Where the scroll is, from 0 to 1 — 0 when there’s nothing to scroll. Read it on scroll for a progress bar.

api.on("scroll", () => bar.style.setProperty("--progress", api.scrollProgress()));

slidesInView

slidesInView(): number[]

The indexes of the slides in view, in order, by inViewThreshold. An IntersectionObserver fills it shortly after the carousel is built, so read it on the slidesInView event rather than right after Spill().

api.on("slidesInView", () => {
  for (const index of api.slidesInView()) api.slideNodes()[index].querySelector("video")?.play();
});

slidesNotInView

slidesNotInView(): number[]

The indexes of the other slides, in order.

Its elements

slideNodes

slideNodes(): HTMLElement[]

The slides, in order — a new array each time. Empty while the carousel is inactive.

containerNode

containerNode(): HTMLElement | null

The slides’ parent (container), or null while the carousel is inactive.

rootNode

rootNode(): HTMLElement

The viewport: the element you passed to Spill(), the box that scrolls.

Plugins and internals

plugins

plugins(): Record<string, SpillPlugin>

The plugins in force, by name. Each is the plugin’s own object, so its methods are there: the built-ins are autoplay, classNames and autoHeight. Empty while the carousel is inactive.

api.plugins().autoplay.stop();
api.plugins().autoplay.isPlaying(); // false

internalEngine

internalEngine(): {
  options: SpillOptions; // the options in force
  slideRegistry: number[][]; // each snap's slides
  scrollSnaps: number[]; // each snap's scroll position, in px
  limit: { min: number; max: number }; // the scroll's range, in px
}

Not Embla’s physics engine: what a plugin needs of the carousel. options are the ones in force — the defaults, the global options, the carousel’s own and its matching breakpoints, merged. slideRegistry lists each snap’s slides (more than one with slidesToScroll, or where trimSnaps joined snaps). scrollSnaps and limit are in pixels from the start, in a right-to-left row too. Read it; for new options, use reInit().

const { slideRegistry } = api.internalEngine();
slideRegistry[api.selectedScrollSnap()]; // [2, 3]: the selected snap's slides

Building and taking down

reInit

reInit(options?: SpillOptions, plugins?: SpillPlugin[]): void

Takes the carousel down and builds it again: the plugins destroyed and started again, the slides found and measured again. options are merged into the ones it has — they add up from one call to the next — and plugins, when given, replace its plugin list. The selected snap is kept, unless options.startIndex says where to start. Then reInit fires. Your listeners stay. After destroy(), it does nothing.

api.reInit({ align: "end" }); // new options
api.reInit(); // the same options, measured again
api.reInit({}, [Autoplay({ delay: 3000 })]); // new plugins

Spill rebuilds by itself when a breakpoint starts or stops matching and when slides are added or removed; when the viewport’s or a slide’s size along the axis changes, it measures again and fires reInit, then resize, as well. Call it yourself when content changed in a way none of them notice.

destroy

destroy(): void

Takes the carousel down for good: the plugins destroyed, every listener and observer removed, and everything Spill wrote — its inline styles, its data-spill-* attributes, a style attribute it added, the room containScroll: false made — taken away, so the markup is as it was. A data-spill-viewport you wrote yourself (as for SpillAuto) stays. Then destroy fires, and every callback is dropped. Calling it again does nothing. Call it when the carousel leaves the page.

api.destroy();

Events

on

on(event: string, callback: (api: SpillApi, event: string) => void): SpillApi

Calls callback each time the event fires, with the API and the event’s name. It returns the API, so calls chain. A callback added twice for the same event runs once.

api.on("init", update).on("reInit", update).on("select", update);

off

off(event: string, callback: (api: SpillApi, event: string) => void): SpillApi

Removes a callback — the same function you gave to on(). It returns the API.

emit

emit(event: string): SpillApi

Fires an event: its callbacks run at once, in the order they were added. Plugins fire their own events with it (autoplay:play); you can too. It returns the API. Every event, and when it fires: Events.

Exports

Spill

Spill(viewport: HTMLElement, options?: SpillOptions, plugins?: SpillPlugin[]): SpillApi

The default export, and a named one. It builds a carousel on the viewport — the box that scrolls — and returns its API. The plugins start inside it; init fires on the next task, after Spill() has returned, so a listener added right after it hears init. Options every carousel starts from: Spill.globalOptions.

import Spill from "@bozdev/spill";
// or: import { Spill } from "@bozdev/spill";

@bozdev/spill/core is the carousel alone, without the plugins and SpillAuto: Spill as its default export, defaultOptions and optionsHandler. More in Modules and bundles.

import Spill from "@bozdev/spill/core";

defaultOptions

defaultOptions: Readonly<Required<SpillOptions>>

Every option’s default, frozen.

import { defaultOptions } from "@bozdev/spill";

defaultOptions.duration; // 25

The built-in plugins export theirs too: autoplayDefaults, classNamesDefaults, autoHeightDefaults.

optionsHandler

optionsHandler: { mergeOptions, optionsAtMedia, optionsMediaQueries }

The helpers a plugin’s init() receives — merging options, applying the breakpoints that match, listing their media queries — and usable on their own. Each one: The options handler.

import { optionsHandler } from "@bozdev/spill";

const now = optionsHandler.optionsAtMedia(myOptions); // with the breakpoints that match now

Without a bundler

With the <script> build, everything hangs on the global Spill: Spill.defaultOptions, Spill.optionsHandler, Spill.Autoplay, Spill.ClassNames, Spill.AutoHeight and Spill.SpillAuto.

Types

The package ships TypeScript types for all of it: SpillApi, SpillOptions, SpillPlugin, SpillEngine, SpillEventName, SpillEventType, SpillEventCallback, SpillAlign, SpillWords (SpillAuto’s labels), and the plugins’ options.

import Spill, { type SpillApi, type SpillOptions } from "@bozdev/spill";

const viewport = document.querySelector<HTMLElement>(".viewport")!;
const options: SpillOptions = { align: "start" };
const api: SpillApi = Spill(viewport, options);
Edit this page on GitHub