Quick start

A carousel step by step — the markup, the CSS, one call, its events, then buttons and dots.

Install Spill first — npm install @bozdev/spill, or a <script> tag (Installation). Then build a carousel in five steps.

The markup

Three levels: a viewport, the box that scrolls; its first child, the container; and the container’s children, the slides.

<div class="viewport">
  <div class="container">
    <div class="slide">1</div>
    <div class="slide">2</div>
    <div class="slide">3</div>
    <div class="slide">4</div>
    <div class="slide">5</div>
  </div>
</div>

Any elements will do — a <ul> of <li>s, a <section> of <figure>s. The class names are yours; Spill finds the container and the slides by their place (the container and slides options name others).

The CSS

The look is your CSS, as with Embla. A row of slides, each 80% of the viewport, 1rem apart:

.viewport { overflow-x: auto; }                     /* before (and without) JavaScript, the row still scrolls */
.container { display: flex; gap: 1rem; }
.slide { flex: 0 0 80%; min-width: 0; }
.viewport[data-spill-draggable] { cursor: grab; }
.viewport[data-spill-dragging] { cursor: grabbing; }

A slide’s flex-basis is its size: 100% shows one at a time, calc((100% - 2rem) / 3) three with a 1rem gap. Spill reads the sizes and never sets them, so change them in media queries as you like.

Spill writes what it needs to work inline — the overflow, the snap type, each snap’s snap point — and takes it away again on destroy(). The two attributes above are hooks it sets for your CSS: data-spill-draggable while a mouse can drag the carousel, data-spill-dragging while it does. More in Markup and CSS.

The call

Give Spill() the viewport:

import Spill from "@bozdev/spill";

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

Spill(viewport, options, plugins) builds the carousel and returns its API. The options are Embla’s — here align: "start" puts each snap at the viewport’s start (the default is "center"). Plugins come third, in an array: [Autoplay()]. With the <script> tag, Spill is a global: leave out the import.

When the carousel leaves the page, take it down:

api.destroy();

Events

The carousel reports what it does. Listen with on():

api.on("select", () => {
  console.log("Selected snap:", api.selectedScrollSnap());
});

api.on("settle", () => console.log("At rest"));

A listener gets the API and the event’s name: (api, eventName). on() returns the API, so calls chain; off(event, listener) removes one. The ones you’ll use most:

Event When
init Built — on the next task after Spill() returns, so a listener added right after the call hears it
select The selected snap changed
scroll It scrolled (once a frame)
settle It came to rest
reInit Rebuilt: a new size, a breakpoint, slides added or removed, reInit()

Every event is on the Events page.

Buttons and dots

Add the controls to the markup — anywhere, they’re plain buttons:

<div class="carousel">
  <div class="viewport">…</div>
  <button class="prev" type="button">Previous</button>
  <button class="next" type="button">Next</button>
  <div class="dots"></div>
</div>

Then wire them to the API:

const prev = document.querySelector(".prev");
const next = document.querySelector(".next");
const dots = document.querySelector(".dots");

prev.addEventListener("click", () => api.scrollPrev());
next.addEventListener("click", () => api.scrollNext());

// 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;
    }),
  );
};

// The selected dot marked, the buttons off at the edges
const update = () => {
  [...dots.children].forEach((dot, index) => {
    dot.setAttribute("aria-current", String(index === api.selectedScrollSnap()));
  });
  prev.disabled = !api.canScrollPrev();
  next.disabled = !api.canScrollNext();
};

const refresh = () => {
  buildDots();
  update();
};

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

A snap is a place the carousel comes to rest. It isn’t always one slide: with slidesToScroll, or slides that fit together at an edge, one snap can hold several. So the dots follow scrollSnapList(), not the slides — and they’re built again on reInit, since a new size, a breakpoint or a new slide can change the snaps.

Style the selected dot with [aria-current="true"], and the buttons with :disabled.

Keep the focus

A disabled button loses the keyboard’s focus. Set aria-disabled="true" instead and ignore its clicks, and a focused button keeps its focus at the edge — the way By attributes does it.

All together

The same steps, live — with the examples’ class names and look. Its code is in the tabs.

Basic

import Spill from "@bozdev/spill";

const root = document.querySelector(".carousel--basic");
const prev = root.querySelector(".carousel__button--prev");
const next = root.querySelector(".carousel__button--next");
const dots = root.querySelector(".carousel__dots");

const api = Spill(root.querySelector(".carousel__viewport"), { 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();
});

Where next

Edit this page on GitHub