SnapDOM API Reference

Usage patterns

Reusable capture

Capture once, export many times (no re-clone):

const el = document.querySelector('#target');
const result = await snapdom(el);

const img = await result.toPng();
document.body.appendChild(img);
await result.download({ format: 'jpg', filename: 'my-capture.jpg' });

One-step shortcuts

Direct export when you need a single format:

const png = await snapdom.toPng(el);
const blob = await snapdom.toBlob(el);
document.body.appendChild(png);

snapdom(el, options?)

Returns a reusable object with export methods. The capture (deep clone + asset inlining) runs once; each method on the returned object reuses it, so exporting several formats from the same element does not re-clone the DOM.

{
  url: string;
  meta: Readonly<{
    w0: number; h0: number;
    vbW: number; vbH: number;
    targetW: number; targetH: number;
    contentX: number; contentY: number;
    clip: Readonly<{ x: number; y: number; width: number; height: number }> | null;
  }>;
  toRaw(): string;
  toImg(): Promise<HTMLImageElement>; // deprecated
  toSvg(): Promise<HTMLImageElement>;
  toCanvas(options?: {
    crop?: { x: number; y: number; width: number; height: number };
  }): Promise<HTMLCanvasElement>;
  toBlob(options?): Promise<Blob>;
  toPng(options?): Promise<HTMLImageElement>;
  toJpg(options?): Promise<HTMLImageElement>;
  toWebp(options?): Promise<HTMLImageElement>;
  download(options?): Promise<void>;
}

toImg() is deprecated: use toSvg() instead.

Shortcut methods

Each shortcut captures and exports in a single call. They accept the same element and the full set of capture options.

Exporter-specific options

Some exporters accept a small set of export-only options in addition to the global capture options.

toCanvas({ crop }) and result.meta

The reusable result can rasterize a rectangular window of its canonical SVG. crop is expressed in SVG viewBox CSS pixels and rewrites the viewBox before image decode, so a long capture can become page- or tile-sized canvases without allocating one full-page bitmap. result.meta is the frozen geometry of that serialized capture.

Use the two-step API shown here. The one-step snapdom.toCanvas(el, options) shortcut does not accept an export crop.

const result = await snapdom(page, { dpr: 1 });
const { contentX, contentY, w0, h0 } = result.meta;

const firstTile = await result.toCanvas({
  crop: {
    x: contentX,
    y: contentY,
    width: Math.min(2048, w0),
    height: Math.min(2048, h0),
  },
  dpr: 1,
});

A partly outside window is intersected with the viewBox. Empty, non-finite, fully outside or non-SVG crop requests reject. Each resulting canvas remains subject to the browser's raster limits after scale × dpr. See the tiled full-page walkthrough and live mosaic for a complete loop and the memory trade-offs.

download()

Example:

await result.download({
  format: 'jpg',
  quality: 0.92,
  filename: 'my-capture'
});

toBlob()

Example:

const blob = await result.toBlob({ type: 'jpeg', quality: 0.92 });