Installation
Install Spill from npm, load it with a script tag from a CDN, or import its ES modules — the types come with it.
Spill has no dependencies and no stylesheet. Install it with a package manager and import it, or load one built file with a <script> tag. Either way, the carousel is the same.
npm, pnpm, yarn
npm install @bozdev/spill
pnpm add @bozdev/spill
yarn add @bozdev/spill
Then import it:
import Spill from "@bozdev/spill";
const api = Spill(document.querySelector(".viewport"), { align: "start" });
The package ships its source as ES modules. Your bundler minifies it and leaves out the parts you don’t import: the core alone is 4.9 KB minified and gzipped.
A script tag
dist/spill.global.js is built for a <script> tag. It defines one global, Spill: the carousel function, with the plugins and SpillAuto on it.
<script src="https://cdn.jsdelivr.net/npm/@bozdev/spill@0.1.0/dist/spill.global.js"></script>
<script>
const api = Spill(document.querySelector(".viewport"), { align: "start" }, [Spill.Autoplay()]);
</script>
On window.Spill |
|
|---|---|
Spill(viewport, options, plugins) |
The carousel |
Spill.Autoplay, Spill.ClassNames, Spill.AutoHeight |
The plugins |
Spill.SpillAuto |
Carousels by attributes — not started: register the plugins you name, then call Spill.SpillAuto.start() |
Spill.defaultOptions, Spill.optionsHandler |
The default options; the options helper plugins get |
Spill.globalOptions |
Options under every carousel’s own |
Put the tags after the carousel’s markup — at the end of the body — so the element is there when your script runs.
By attributes
dist/spill.auto.js is the same file, started: the three plugins are registered for data-spill-plugins, and every [data-spill-carousel] on the page builds itself. No script of your own:
<script src="https://cdn.jsdelivr.net/npm/@bozdev/spill@0.1.0/dist/spill.auto.js"></script>
It waits for the document to be parsed, so it can go in the <head> too. It also defines window.Spill. See By attributes for the markup.
unpkg
The same files are on unpkg:
<script src="https://unpkg.com/@bozdev/spill@0.1.0/dist/spill.global.js"></script>
Without a file path, both CDNs serve dist/spill.global.js — the package names it in its jsdelivr and unpkg fields.
Pin the version
Keep the exact version in the URL (@0.1.0). A page that loads whatever is newest can change under you.
ES modules
From the package
The package’s entry points, each with its types:
| Import | What it gives |
|---|---|
@bozdev/spill |
Every part, by name: Spill (also the default export), Autoplay, ClassNames, AutoHeight, SpillAuto, defaultOptions, optionsHandler, and the plugins’ defaults (autoplayDefaults, classNamesDefaults, autoHeightDefaults) |
@bozdev/spill/core |
The carousel alone: Spill (the default export), defaultOptions, optionsHandler |
@bozdev/spill/plugins/autoplay |
Autoplay (the default export) |
@bozdev/spill/plugins/class-names |
ClassNames |
@bozdev/spill/plugins/auto-height |
AutoHeight |
@bozdev/spill/attributes |
SpillAuto — nothing registered, not started |
@bozdev/spill/auto |
Carousels by attributes, started: the three plugins registered and SpillAuto.start() called when it’s imported. It also exports what @bozdev/spill does, the default Spill too |
@bozdev/spill/dist/... |
The built files below |
// The carousel, and any other part by name
import Spill, { Autoplay, ClassNames, SpillAuto } from "@bozdev/spill";
// One part from its own module
import Spill from "@bozdev/spill/core";
import Autoplay from "@bozdev/spill/plugins/autoplay";
import { SpillAuto } from "@bozdev/spill/attributes";
// By attributes: every [data-spill-carousel] on the page builds itself
import "@bozdev/spill/auto";
// Built and minified: every part in one file…
import { Spill, Autoplay } from "@bozdev/spill/dist/spill.esm.js";
// …or the core alone
import Spill from "@bozdev/spill/dist/esm/spill.js";
In the browser, without a bundler
A browser doesn’t know the package’s name. Map it to a CDN’s file with an import map, or import the file’s URL:
<script type="importmap">
{
"imports": {
"@bozdev/spill": "https://cdn.jsdelivr.net/npm/@bozdev/spill@0.1.0/dist/spill.esm.js"
}
}
</script>
<script type="module">
import { Spill, Autoplay } from "@bozdev/spill";
Spill(document.querySelector(".viewport"), { align: "start" }, [Autoplay()]);
</script>
<script type="module">
import Spill from "https://cdn.jsdelivr.net/npm/@bozdev/spill@0.1.0/dist/esm/spill.js";
import Autoplay from "https://cdn.jsdelivr.net/npm/@bozdev/spill@0.1.0/dist/esm/plugins/autoplay.js";
Spill(document.querySelector(".viewport"), { align: "start" }, [Autoplay()]);
</script>
What’s in dist/
Built and minified. The sizes are each file’s own: minified, then compressed with gzip and with Brotli (1 KB = 1000 bytes):
| File | What | Minified | gzip | Brotli |
|---|---|---|---|---|
spill.esm.js |
Every part, one ES module (the same exports as @bozdev/spill) |
21.3 KB | 8.0 KB | 7.3 KB |
spill.global.js |
For a <script> tag: window.Spill |
21.7 KB | 8.2 KB | 7.5 KB |
spill.auto.js |
For a <script> tag, by attributes: window.Spill, the plugins registered, SpillAuto started |
21.9 KB | 8.3 KB | 7.5 KB |
esm/spill.js |
The core alone (what @bozdev/spill/core is) |
12.6 KB | 4.9 KB | 4.5 KB |
esm/attributes.js |
SpillAuto (it imports ./spill.js) |
5.2 KB | 2.2 KB | 2.0 KB |
esm/plugins/autoplay.js |
Autoplay | 1.9 KB | 1.0 KB | 0.8 KB |
esm/plugins/class-names.js |
ClassNames | 1.3 KB | 0.7 KB | 0.6 KB |
esm/plugins/auto-height.js |
AutoHeight | 0.8 KB | 0.5 KB | 0.4 KB |
The files in esm/ are the source’s modules one by one: load the core alone, and a plugin only where a carousel uses it. For comparison, Embla’s core (8.6.0, measured the same way) is 17.9 KB minified, 7.2 KB gzip.
TypeScript
The types come with the package, in types/ — there’s no separate @types package to install. Each entry point names its own, so TypeScript finds them through the package’s exports (moduleResolution set to "bundler", "node16" or "nodenext").
import Spill, { Autoplay } from "@bozdev/spill";
import type { AutoplayType, SpillApi, SpillOptions } from "@bozdev/spill";
const options: SpillOptions = { align: "start", slidesToScroll: "auto" };
const viewport = document.querySelector<HTMLElement>(".viewport")!;
const api: SpillApi = Spill(viewport, options, [Autoplay({ delay: 5000 })]);
api.on("select", (carousel) => console.log(carousel.selectedScrollSnap()));
const autoplay = api.plugins().autoplay as AutoplayType;
autoplay.stop();
| Type | |
|---|---|
SpillApi |
A carousel’s API: what Spill() returns |
SpillOptions |
The options |
SpillAlign |
align’s value: "start", "center", "end", or a function |
SpillPlugin |
A plugin’s shape: name, options, init(), destroy() and its own methods |
SpillEngine |
What internalEngine() returns |
SpillEventName |
The core’s events |
SpillEventType |
An event name: the core’s, or a plugin’s ("autoplay:play") |
SpillEventCallback |
A listener: (api, eventName) => void |
AutoplayOptions, ClassNamesOptions, AutoHeightOptions |
Each plugin’s options |
AutoplayType, ClassNamesType, AutoHeightType |
Each plugin’s instance, with its methods |
SpillWords |
The labels SpillAuto writes (By attributes) |
api.plugins() gives the plugins as SpillPlugins; cast one to its own type, as above, for its methods. SpillAuto.get() returns a SpillApi or null, and SpillAuto.all() a Map<HTMLElement, SpillApi>. The built files in dist/ have no types of their own: from TypeScript, import the entry points.