Flip Book for the modern web.

createFlipbook(options)

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

createFlipbook({
  container: HTMLElement,
  pages: readonly PageSource[],
  initialPage?: number,        // default 0
  axis?: "horizontal" | "vertical", // default "horizontal"
  radius?: number,             // curl radius (clip-space). Default 0.35
  tilt?: number,               // hinge tilt (radians). Default 0.12
  backColor?: [r, g, b],       // page-back colour. Default cream
  flipDuration?: number,       // tween duration (ms). Default 900
  ease?: EasingFn,             // default cubicInOut from @vysmo/easings
  loop?: boolean,              // wrap at the ends. Default false
  clickNavigation?: boolean,   // click halves to flip. Default true
  dragNavigation?: boolean,    // pointer-drag scrub. Default true
  dragCommitThreshold?: number,// release-past commits the flip. Default 0.5
  keyboardNavigation?: boolean,// arrows, Home, End. Default true
  autoplay?: boolean | { intervalMs: number }, // default off
  ariaLabel?: string,          // default "Flipbook"
}): FlipbookHandle

FlipbookHandle

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

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

  // Resolves once every page source has decoded. Safe to call methods
  // before this resolves — they queue until the first frame is ready.
  readonly ready: Promise<void>;

  // Imperative navigation
  next(): Promise<void>;
  prev(): Promise<void>;
  goTo(index: number, options?: { instant?: boolean }): Promise<void>;

  // Externally-driven progress (scroll, scrub, custom gestures).
  // 0 = idle on `current`; 1 = commit to next; mid-curl in between.
  seek(progress: number): void;

  // Autoplay control. play() and pause() are no-ops if already in state.
  play(): void;
  pause(): void;

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

  destroy(): void;
}

PageSource

Anything you can hand to a page slot. Strings are URLs; DOM element variants are used as-is. Rich-DOM pages are out of scope — pre-render to a canvas if you need text overlays, dynamic content, or HTML.

// Anything you can hand to a flipbook page slot.
type PageSource =
  | string                 // URL — decoded as an image at construction time
  | HTMLImageElement       // already-decoded image, used as-is
  | HTMLCanvasElement;     // pre-rendered canvas (for rich DOM pages)

Events

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

• change(current, previous) — emitted after a commit. current is the new page index.
• flipstart(from, to) — emitted when a flip begins. Fires after click / drag-commit / autoplay tick.
• flipend(from, to) — emitted when the curl tween settles. change fires fractionally before flipend.