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

Pass content-selection options when capturing. filter and exclude can be used together, with independent filterMode and excludeMode settings. A new call with function-valued filter, exclude, excludeStyleProps or fallbackURL evaluates current callback state instead of serving an unchanged memo. A closure change needs no invalidate; an existing result remains frozen and its exporters do not reapply a changed policy.

{
  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 a single call. They accept the same element and the full set of capture options. The table describes the default SVG engine.

SnapDOM's second engine, experimental html-in-canvas, needs the browser feature flag and an enabled build; see engine requirements. 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. Event handlers in the markup can run in your origin. Sanitize untrusted input before calling this method; fromString() is not a sanitizer or a server-side renderer.

Exporter-specific options

Export options override the values captured with the result. width or height takes precedence over scale; dpr multiplies raster pixels. toCanvas({ crop: { x, y, width, height } }) rasterizes one rectangle of the capture, in result.meta coordinates, so a page past the canvas limit can be exported in pieces at full resolution (example). To exclude content before capture work runs, use the capture clip option.

download()

Example:

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

toBlob()

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

Example:

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

Capture boundaries and working recipes

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