API

Name: zinejs
Availability: InStock

Methods and events on a Zine instance. Construction is synchronous; first paint is async.

import { Zine, ImageSource } from '@zinejs/core'

const book = new Zine(document.getElementById('book'), {
  source: new ImageSource([...urls]),
})

await book.ready // optional: wait for first paint before driving methods

Navigation

readyPromise<void>: Resolves when the first spread is painted. Optional for display-only embeds.
flipNext() / flipPrev() / flipTo(page): Turn pages. page is zero-based.
canFlipNext() / canFlipPrev(): Whether another spread exists in that direction.
getPage() / getPageCount(): Current leading page and total count (including covers).
pageLink(page?): Absolute URL that opens the book at page (default: current), for sharing.

Spreads & layout

getSpreads() / getSpreadIndex(): How pages are grouped and which spread is on screen.
getSpreadMode() / setSpreadMode(mode) / toggleSpreadMode(): Configured grouping and runtime switch between one and two pages (toggle restores the original mode).
isSinglePage() / isResponsiveSingle(): Whether one page is showing, and whether that is because the container is narrow.
getResponsiveSpread() / setResponsiveSpread(on): Allow or forbid the narrow-container single-page override.
getDirection(): Current reading direction.
getPageBox(): Where the book is painted inside the container, in container pixels (aspect-fitted). null before the first paint.
container: The host element the book was mounted into.
update(): Re-measure after unusual layout changes (ResizeObserver covers normal resizes).
destroy(): Tear down DOM, listeners, and GPU context.

Zoom

getZoom() / getMaxZoom(): Current scale and ceiling.
setZoom(scale, center?) / resetZoom(): Zoom programmatically. center is container-local { x, y }.

Document features

Mostly for PDFs (image books return false / empty where not applicable).

isDocument(): Whether the book is a document (PDF) rather than loose images.
canSearch() / search(query, opts?): Text search over page text. Returns { page, excerpt }[], at most one hit per page, default cap 50 ( search(query, { limit })). Needs a source that implements getText (PdfSource does).
canDownload() / download(): Save the original file when available. getSourceFile() returns the same payload download() uses, without triggering a save.
canPrint() / print(): Print the original document in an offscreen frame (not the host page chrome). Hidden when the browser reports navigator.pdfViewerEnabled === false (for example Android Chrome).
getSourceFile(): The original file, if any ( { url, filename, revoke? }).
canOutline() / getOutline(): Table of contents when the PDF provides one.
getPageImage(index): One page’s raster for thumbnails or export.

Events

book.on(event, listener) returns an unsubscribe function.

'ready': First spread painted.
'flipStart' / 'flipEnd' / 'pageChanged': Page turns.
'spreadChanged'{ mode, singlePage }: Pages regroup (API call or narrow container). Useful for sizing custom chrome.
'zoomChanged': Zoom scale changed.
'progress'{ loaded, total }: Document download bytes. Only sources that report progress (a PDF from a URL). Hide a custom indicator on ready.
'sourceError' / 'rendererFallback': Page load failure, or renderer fallback (e.g. webgl2 → css).

Controls API

defineControl(spec): Register a custom toolbar control (or override a built-in by id). Use its id in controls.items.
getControl(id): Look up a registered control definition.

Try methods live in the programmatic example.