Slideshow for the modern web.

createSlideshow(options)

Constructs a slideshow in the given container and returns a handle. All options except container and slides have sensible defaults. Mutating the returned handle is the only way to drive the slideshow at runtime — there's no React-style re-render-with-new-options pattern.

createSlideshow({
  container: HTMLElement,
  slides: readonly SlideSource[],
  initial?: number,                // start index (default 0)
  transition?: TransitionSelector, // default `dissolve`
  transitionDuration?: number,     // milliseconds (default 800)
  ease?: EasingFn,                 // from @vysmo/easings (default linear)

  // — Behavior —
  autoplayDelay?: number,          // ms between slides; 0 disables (default 0)
  autoplay?: boolean,              // start playing on mount; default autoplayDelay > 0
  loop?: boolean,                  // wrap at the ends (default true)
  pauseOnHidden?: boolean,         // honor visibilitychange (default true)
  pauseOnHover?: boolean,          // pause autoplay while hovered (default false)

  // — Input —
  clickNavigation?: boolean,       // click halves to advance/retreat (default true)
  keyboardNavigation?: boolean,    // arrows / Home / End / Space (default true)
  swipeNavigation?: boolean | { threshold?: number }, // touch swipe (default false)

  // — Chrome (visible UI overlays — opt in per piece) —
  arrows?: boolean | ArrowsOptions,     // nav buttons
  dots?: boolean | DotsOptions,         // page indicator
  counter?: boolean | CounterOptions,   // "1 / N" text
  progress?: boolean | ProgressOptions, // autoplay countdown bar
  captions?: false | CaptionsOptions,   // per-slide text overlay

  ariaLabel?: string,              // default "Slideshow"
}): SlideshowHandle

SlideshowHandle

The return value of createSlideshow. Reactive state via getters (current, length, isPlaying, isTransitioning), imperative navigation, autoplay control, event subscriptions. destroy() tears down the WebGL context, removes event listeners, and detaches the canvas.

interface SlideshowHandle {
  // Reactive state (getters)
  readonly current: number;
  readonly length: number;
  readonly isPlaying: boolean;
  readonly isTransitioning: boolean;

  // Resolves once every URL/image source has decoded. Canvas sources
  // resolve instantly. Methods called before `ready` are queued.
  readonly ready: Promise<void>;

  // Imperative navigation. All return Promises that resolve when the
  // transition (or instant snap) completes.
  next(): Promise<void>;
  prev(): Promise<void>;
  go(index: number, options?: { instant?: boolean }): Promise<void>;

  // Autoplay control. play() and pause() are no-ops if already in state.
  // play() requires `autoplayDelay > 0` to do anything.
  play(): void;
  pause(): void;

  // Events
  on(event: "change",          cb: (current: number, previous: number) => void): () => void;
  on(event: "transitionstart", cb: (from: number,    to: number) => void): () => void;
  on(event: "transitionend",   cb: (from: number,    to: number) => void): () => void;

  destroy(): void;
}

SlideSource

Anything you can hand to a slide slot. Strings are URLs; DOM-element variants are used as-is. Native video sources are deferred to v2 — for now, paint video frames into a canvas externally and pass that.

// Anything you can hand to a slide slot.
type SlideSource =
  | string                 // URL — decoded as an image at construction time
  | HTMLImageElement       // already-decoded image, used as-is
  | HTMLCanvasElement;     // pre-rendered canvas (paint video frames here)

TransitionSelector

Single transition or function-of-indices. The function form runs on every slide change, so callers can vary per pair, per content type, or by random pool draw — and the slideshow handles the program-cache warmup automatically across the set.

// Pick a single transition for every slide change, or vary per-slide.
type TransitionSelector =
  | Transition                                              // single transition
  | ((fromIndex: number, toIndex: number) => Transition);   // function form

Events

show.on(event, cb) returns an unsubscriber. Call it to detach without tearing down the whole slideshow.

• change(current, previous) — emitted after a transition commits. current is the new index.
• transitionstart(from, to) — emitted when a slide change begins. Fires once per next / prev / go / autoplay tick.
• transitionend(from, to) — emitted when the transition tween settles. change fires fractionally before transitionend.

Keyboard map

When keyboardNavigation is on (default), the container responds to:

• ArrowLeft / ArrowRight — prev / next
• Home / End — first / last slide
• Space — toggle autoplay (no-op if autoplayDelay is 0)