Events
What a carousel fires, when, and in what order — and how to listen.
A carousel tells you what happens through events, with Embla’s names. Move this one with the buttons, a mouse, a finger or a trackpad, and watch what it fires:
Events
<div class="carousel carousel--events">
<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>
<ol class="carousel__log" aria-label="Events, newest first"></ol>
</div>/* The log: six lines, a fixed height — a new line never moves the page */
.carousel--events .carousel__log {
display: grid;
grid-auto-rows: 1.5rem;
box-sizing: border-box;
height: 10.5rem;
margin: 1rem 0 0;
padding: 0.75rem 1rem;
overflow: hidden;
border-radius: 1rem;
list-style: none;
font: 0.8rem/1.5rem var(--font-mono, monospace);
color: var(--muted, #a0a0aa);
background: var(--surface-2, #18181c);
}
.carousel--events .carousel__log li {
display: flex;
gap: 0.75rem;
margin: 0;
white-space: nowrap;
}
.carousel--events .carousel__log-name {
flex: 0 0 15ch;
color: var(--accent-text, #b39af7);
}
.carousel--events .carousel__log-detail {
min-width: 0;
overflow: hidden;
text-overflow: ellipsis;
}
.carousel--events .carousel__log-count {
margin-left: auto;
}
/* The newest line stands out; the older ones fade */
.carousel--events .carousel__log li:first-child {
color: var(--text, #e6e6ec);
}
.carousel--events .carousel__log li:nth-child(n + 4) {
opacity: 0.6;
}import Spill from "@bozdev/spill";
const root = document.querySelector(".carousel--events");
const prev = root.querySelector(".carousel__button--prev");
const next = root.querySelector(".carousel__button--next");
const log = root.querySelector(".carousel__log");
const api = Spill(root.querySelector(".carousel__viewport"), { align: "start" });
prev.addEventListener("click", () => api.scrollPrev());
next.addEventListener("click", () => api.scrollNext());
// What a line says about an event, read from the API as it fires
const details = {
select: (carousel) => `snap ${carousel.selectedScrollSnap()}`,
settle: (carousel) => `snap ${carousel.selectedScrollSnap()}`,
scroll: (carousel) => `${Math.round(carousel.scrollProgress() * 100)}%`,
slidesInView: (carousel) => `[${carousel.slidesInView().join(", ")}]`,
};
const span = (part, text = "") => {
const element = document.createElement("span");
element.className = `carousel__log-${part}`;
element.textContent = text;
return element;
};
// The log: newest first, six lines at most. The same event again (a scroll, frame after frame) counts up on its line.
let newest = null;
const write = (carousel, name) => {
const detail = details[name]?.(carousel) ?? "";
if (newest?.name === name) {
newest.count += 1;
newest.detail.textContent = detail;
newest.counter.textContent = `×${newest.count}`;
return;
}
const line = document.createElement("li");
newest = { name, count: 1, detail: span("detail", detail), counter: span("count") };
line.append(span("name", name), newest.detail, newest.counter);
log.prepend(line);
log.children[6]?.remove();
};
// Every event of the core. Each callback gets the API and the event's name.
const events = ["init", "reInit", "destroy", "select", "scroll", "settle", "resize", "slidesInView", "slidesChanged", "slideFocusStart", "slideFocus", "pointerDown", "pointerUp"];
for (const name of events) api.on(name, write);Listening
api.on(event, callback) calls the callback each time the event fires, with two arguments: the carousel’s API and the event’s name. api.off(event, callback) removes it again — the same function. Both return the API, so calls chain.
import Spill from "@bozdev/spill";
const api = Spill(document.querySelector(".viewport"), { align: "start" });
const label = document.querySelector(".label");
const update = (api, event) => {
label.textContent = `${event}: snap ${api.selectedScrollSnap() + 1}`;
};
api.on("init", update).on("reInit", update).on("select", update);
// later
api.off("select", update);
- Callbacks run at once, in the order they were added; what they return is ignored.
- A callback added twice for the same event runs once.
- Listeners stay through
reInit().destroy()firesdestroy, then drops them all. - Add them right after
Spill()returns:initfires on the next task, so it’s heard.
The core’s events
| Event | Fires when |
|---|---|
init |
The carousel was built — once |
reInit |
It was rebuilt, or measured again after a new size |
destroy |
It was taken down |
select |
The selected snap changed |
scroll |
It scrolled — at most once a frame |
settle |
It came to rest — once a move |
resize |
It was measured again after a size changed |
slidesInView |
The slides in view changed |
slidesChanged |
Slides were added or removed |
slideFocusStart |
Focus landed inside a slide |
slideFocus |
That slide’s snap was brought into place |
pointerDown |
A press on the viewport |
pointerUp |
That press ended |
init
Once, when the carousel is built — on the next task after Spill() returns, with the plugins already started. It fires even when the carousel is inactive (active: false). A rebuild fires reInit instead.
reInit
After the carousel is rebuilt — by api.reInit(), a breakpoint that starts or stops matching, or slides added or removed — and after it’s measured again because the viewport’s or a slide’s size along the axis changed. The snaps may have changed: build the dots again and update the buttons here. A rebuild doesn’t fire select, even when it leaves fewer snaps and the selected one changes with them, so listen to both.
destroy
When api.destroy() has taken everything down. Every callback is dropped right after it.
select
When the selected snap changes:
- a programmatic move —
scrollTo(),scrollNext(),scrollPrev(), a focus: at once, as the move starts; - a finger, a trackpad or the wheel: during the scroll, as soon as another snap is the nearest;
- a mouse’s drag: at the release, with the snap the throw is headed for;
- a mouse’s throw with
dragFree: when the row stops, with the nearest snap.
Read selectedScrollSnap() and previousScrollSnap() in it.
scroll
Whenever the viewport scrolls, whatever moves it — at most once a frame. Read scrollProgress() in it for a progress bar.
settle
When the carousel comes to rest after moving, once a move: at the end of a programmatic move, on the browser’s scrollend where it has one, or after 150 ms without a scroll. Not while a mouse still holds it.
resize
After Spill measured the carousel again because the viewport or a slide changed size along the axis, by half a pixel or more — right after reInit. A slide that only grows taller in a row is no resize.
slidesInView
When the set of slides in view changes, by inViewThreshold: during a scroll, and once shortly after the carousel is built or rebuilt, when its IntersectionObserver first reports. Read slidesInView() and slidesNotInView() in it.
slidesChanged
After slides were added to the container or removed from it (watchSlides) — right after the rebuild’s reInit.
slideFocusStart and slideFocus
When focus lands inside a slide (watchFocus): slideFocusStart first; then Spill starts the move to that slide’s snap (select, if the snap changes), and slideFocus follows. The scroll goes on after them.
pointerDown and pointerUp
pointerDown fires on every press on the viewport — any mouse button, a finger or a pen — before anything else; a move in progress stops there. pointerUp ends every press that fired pointerDown: when the button, the finger or the pen comes up, wherever it is by then, or when the browser cancels the press (pointercancel) — as it does when a finger’s press turns into a scroll. A press in a form field and a press with watchDrag: false fire both too. After a mouse’s drag, pointerUp comes at the release, before the throw’s select.
In what order
| What happens | The events |
|---|---|
Spill() |
init on the next task; slidesInView when the observer first reports |
A button: scrollNext() |
select → scroll … → settle |
| A finger | pointerDown → pointerUp as the scroll takes over → scroll … (select whenever another snap is nearest) → settle |
| A trackpad or the wheel | scroll … (select whenever another snap is nearest) → settle |
| A mouse’s drag | pointerDown → scroll … → pointerUp → select → scroll … → settle |
| A click, a tap | pointerDown → pointerUp |
| Tab into a slide | slideFocusStart → select → slideFocus → scroll … → settle |
| A new size | reInit → resize |
| Slides added or removed | reInit → slidesChanged |
reInit(), a breakpoint |
reInit |
destroy() |
destroy |
select comes only when the snap changes, and slidesInView whenever the slides in view do. The plugins start inside Spill() and again on each rebuild, before init or reInit — so the events they fire as they start come first.
Plugin events
A plugin fires its own events on the carousel, named after it, and you listen to them the same way. Autoplay fires these:
| Event | Fires when |
|---|---|
autoplay:play |
It starts playing: play(), playOnInit as the carousel is built or rebuilt, the mouse leaving with stopOnMouseEnter |
autoplay:stop |
It stops: stop(), a press with stopOnInteraction, a focus inside with stopOnFocusIn, the mouse entering with stopOnMouseEnter, the last snap with stopOnLastSnap |
autoplay:select |
It has just moved the carousel on — after the core’s select |
autoplay:timerset |
A countdown to the next move started |
autoplay:timerstopped |
A running countdown was cleared: stopped, paused by a press, the page hidden, started over, taken down |
ClassNames and AutoHeight fire none.
The first play happens inside Spill()
With playOnInit (the default), Autoplay starts — and fires autoplay:play — while Spill() runs, before you can listen. Read isPlaying() on init for the state it starts in, and follow it from there.
import Spill from "@bozdev/spill";
import Autoplay from "@bozdev/spill/plugins/autoplay";
const api = Spill(viewport, { align: "start" }, [Autoplay({ delay: 5000 })]);
const update = () => playButton.setAttribute("aria-pressed", String(api.plugins().autoplay.isPlaying()));
api.on("init", update).on("autoplay:play", update).on("autoplay:stop", update);
Your own events
api.emit(event) fires any event by name, and its callbacks run at once. Give your own a prefix, as Autoplay does — it’s how a plugin of your own tells the page what it did.
api.on("gallery:open", () => dialog.showModal());
api.emit("gallery:open");
spill:ready
A carousel built by attributes has no Spill() call of yours to keep its API. SpillAuto hands it over with a DOM event instead: spill:ready, fired on the carousel’s element as it’s built. It bubbles, and event.detail.api is the API. It comes before the carousel’s init, so a listener added there hears init too.
import { SpillAuto } from "@bozdev/spill/attributes";
import Autoplay from "@bozdev/spill/plugins/autoplay";
document.addEventListener("spill:ready", (event) => {
const { api } = event.detail;
const carousel = event.target; // the [data-spill-carousel] element
api.on("select", () => {
carousel.dataset.snap = api.selectedScrollSnap();
});
});
SpillAuto.plugins = { autoplay: Autoplay };
SpillAuto.start();
Add the listener before SpillAuto starts. @bozdev/spill/auto starts it as soon as it’s imported — an import runs before the rest of your module — so the carousels already on the page can be built before your listener is there. For a carousel that’s already built, SpillAuto.get(element) returns its API (null when the element is in no carousel SpillAuto built).