SnapDOM API Reference

Usage patterns

Reusable capture

Keep the result to create a preview and a downloaded file from the same state:

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, { format: 'png' });
document.body.appendChild(png);

snapdom(el, options?)

Returns export methods, immutable capture geometry (meta) and diagnostics (warnings). Pass capture options here; later exports can change output size, format and quality.

Set filter and exclude when capturing. Exporters keep that captured content. Function-valued policies run again on each new capture; see callback and cache behavior.

{
  url: string;                    // SVG by default; PNG after native capture
  needs: 'clone' | 'render';
  meta: Readonly<CaptureMeta>;
  warnings: Array<{ code: string; message: string; detail?: unknown }>;
  toRaw(): string;
  to(type, options?): Promise<unknown>;
  toImg(options?): Promise<HTMLImageElement>; // deprecated
  toSvg(options?): Promise<HTMLImageElement>;
  toCanvas(options?): Promise<HTMLCanvasElement>;
  toBlob(options?): Promise<Blob>;
  toPng(options?): Promise<HTMLImageElement>;
  toJpeg(options?): Promise<HTMLImageElement>;
  toJpg(options?): Promise<HTMLImageElement>;
  toWebp(options?): Promise<HTMLImageElement>;
  download(options?): Promise<void>;
}

With the default SVG engine, url and toRaw() return serialized SVG without drawing pixels. A successful native capture lazily encodes PNG instead. toImg() is deprecated; use toSvg(). Frozen meta records the viewBox size, output target, content origin and clip rectangle. A plugin capture that stops at needs: 'clone' has no rendered image or render metadata; image access throws.

Shortcut methods

Each shortcut captures and exports in one call, with the same element and the full set of capture options. The table describes the default SVG engine.

SnapDOM's second engine, html-in-canvas, runs in Chrome 157 and newer and falls back to SVG elsewhere; see the engine option. On a successful native capture, toRaw() returns PNG, toSvg() returns a PNG-backed image, and toBlob() defaults to PNG. There is no SVG source; requesting an SVG Blob rejects. SVG fallback uses the table's behavior.

Other top-level API

snapdom.fromString(html, options?)

Capture trusted markup such as a template or SSR output in the browser. SnapDOM mounts it offscreen so the page's CSS and fonts apply, captures it, then removes the mount. A single root element becomes the target; multiple roots use the mount's wrapper.

const result = await snapdom.fromString(
  '<article class="card"><h2>Hello</h2></article>'
);
const png = await result.toPng();

Trusted HTML only. The mount uses innerHTML in your page, so event handlers in the markup can run in your origin. Sanitize untrusted input first; fromString() is not a sanitizer or a server-side renderer.

Exporter-specific options

Export options override capture defaults. width or height wins over scale; dpr multiplies raster pixels.

Large PNG and JPEG files

Use download() or toBlob() for a file that exceeds canvas limits. From an SVG capture, SnapDOM automatically encodes bounded windows into one PNG or JPEG at the requested size. You do not need to calculate crops or join images.

const result = await snapdom(document.body);
await result.download({ format: 'png', filename: 'full-page' });
const blob = await result.toBlob({ format: 'jpeg', quality: 0.92 });

Oversized PNG encoding requires CompressionStream. JPEG supports at most 65,535 pixels per side. toPng(), toCanvas(), WebP and exports outside those conditions retain proportional downscaling and report raster-clamp or canvas-clamp warnings.

download()

download() always rasterizes at DPR 1, so the file matches the element's CSS size and a dpr option is ignored. Pass scale: devicePixelRatio for a file as sharp as the screen.

Example:

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

toBlob()

Without a format set at capture or export time, toBlob() defaults to SVG on the SVG engine and PNG after successful native capture. A result created with snapdom(el, { format: 'png' }) uses PNG for result.toBlob() too.

Example:

const blob = await result.toBlob({ format: 'png' });

Export a region

toCanvas({ crop: { x, y, width, height } }) rasterizes a rectangle of an existing SVG capture in viewBox coordinates, including bleed and padding (example). To leave content out before capture work runs, use the capture clip option, which uses page coordinates.

Capture boundaries and working recipes

For embedded documents, see the same-origin iframe recipe; browser JavaScript cannot read cross-origin frames. For custom elements, see the open Shadow DOM recipe or the Lit component guide. For a PNG Blob instead of an image element, use the upload recipe and request format: 'png'.