SnapDOM Options

All options

All capture methods accept an options object.

html-in-canvas runs where the browser exposes drawElementImage(): Chrome 157 and newer, without a flag. Firefox and Safari have no implementation. There, and on any capture the native engine cannot paint (body and html roots, transformed or zoomed ancestors, clip, width/height, outerShadows, plugins with render hooks), SnapDOM runs the SVG engine on the same clone, so the option is safe to set without a feature check. SVG stays the default because it is faster: the native paint waits for a rendering update. The guide says when to pick which; the lab compares both engines and lists which plugins run on each.

A successful native capture is a bitmap: url/toRaw() lazily encode PNG, toSvg() returns a PNG-backed image, and toBlob() defaults to PNG unless a format was set. Requesting an SVG Blob from it rejects. Use engine: 'svg' when you need serialized SVG.

debug

SnapDOM logs nothing to the console by default. Set debug: true to log fallbacks and errors with the [SnapDOM] prefix: failed fetches, cross-origin iframes, downscaled exports, invalid exclude selectors. Without it, result.warnings records capture fallbacks and limits.

await snapdom.toPng(el, { debug: true });

Automatic image downsampling

SnapDOM reduces oversized raster assets to the resolution the requested output needs, accounting for output size, transforms and DPR. It preserves aspect ratio and never upscales the source. This covers <img>, captured canvas/video frames, non-repeating backgrounds and SVG <image>.

The benefit depends on the export:

• Raster exports decode smaller embedded images, which saves work when sources are much larger than their display size.
• SVG exports carry smaller image data. url and toRaw() return that serialized capture without rasterizing it.

The SVG engine keeps the original asset data, so later exports at a larger resolution still have it. Images that already fit are left alone. A native-engine capture is a bitmap, so enlarging it scales the captured pixels.

Fallback image on <img> load failure

Provide a default image for failed <img> loads: a fixed URL, or a callback that receives measured dimensions and returns a URL (handy for dynamic placeholders).

// 1) Fixed URL fallback
await snapdom.toSvg(element, {
  fallbackURL: '/images/fallback.png'
});

// 2) Dynamic placeholder via callback
await snapdom.toSvg(element, {
  fallbackURL: ({ width = 300, height = 150 }) =>
    `https://placehold.co/${width}x${height}`
});

// 3) With proxy (if your fallback host has no CORS)
await snapdom.toSvg(element, {
  fallbackURL: ({ width = 300, height = 150 }) =>
    `https://dummyimage.com/${width}x${height}/cccccc/666.png&text=img`,
  useProxy: 'https://proxy.corsfix.com/?'
});

Notes:

• If the fallback also fails, the <img> keeps its box and shows a grey placeholder, and result.warnings lists its URL.
• The callback's width/height come from the original element (dataset, style/attrs, etc.) when available.
• The callback also gets src, so it can send only the images that failed through your own proxy: see Capture images without CORS.

Dimensions (scale, width, height)

• width or height takes precedence over scale. dpr still multiplies raster pixels.
• Only width: height scales proportionally (and vice versa).
• Both width and height: exact size, may distort.

Cross-Origin Images & Fonts (useProxy)

Set useProxy to a proxy you trust for assets the browser cannot read directly:

await snapdom.toPng(el, {
  useProxy: 'https://your-proxy.example/?url='
});

• When configured, the proxy handles cross-origin resource requests, including assets that already allow CORS. Same-origin and already-proxied URLs skip it.

Fonts

embedFonts

The default, 'auto', embeds webfonts used by the capture and skips font discovery for system-font-only content. Use true to force discovery or false to skip text-font embedding. Icon-font glyphs use a separate rendering path.

localFonts

Declare font files or data URLs when stylesheet discovery cannot supply them:

await snapdom.toPng(el, {
  embedFonts: true,
  localFonts: [
    { family: 'Inter', src: '/fonts/Inter-Variable.woff2', weight: 400, style: 'normal' },
    { family: 'Inter', src: '/fonts/Inter-Italic.woff2', style: 'italic' }
  ]
});

iconFonts

Add custom icon families (names or regex matchers). Useful for private icon sets:

await snapdom.toPng(el, {
  iconFonts: ['MyIcons', /^(Remix|Feather) Icons?$/i]
});

excludeFonts

Skip specific non-icon fonts to speed up capture or avoid downloads.

await snapdom.toPng(el, {
  embedFonts: true,
  excludeFonts: {
    families: ['Noto Serif', 'SomeHeavyFont'],     // skip by family name
    subsets: ['cyrillic-ext']                      // skip by unicode-range subset tag
  }
});

Notes

• excludeFonts applies to text-font embedding, not the icon-font rendering path.
• Matching is case-insensitive for families. Hosts are matched by substring against the resolved URL.

Selecting content: filter and exclude

Combine filter and exclude with independent layout modes. The CSS-effect filter plugin is a separate feature.

• filter: a synchronous predicate. True keeps a node; any falsy return filters it out.
• filterMode: hide keeps an invisible spacer for filtered nodes; remove drops them and allows reflow. Defaults to hide.
• exclude: a selector, a synchronous boolean predicate, or any mix of both in an array. A node is excluded if any rule matches.
• excludeMode: the separate hide/remove mode for exclusions; defaults to hide. Both modes omit the affected node's content.

// Hide private fields while preserving space; remove the toolbar.
await snapdom(el, {
  filter: node => !node.matches('[data-private]'),
  filterMode: 'hide',
  exclude: ['.toolbar'],
  excludeMode: 'remove'
});

Per node, data-capture="exclude" is checked first, then exclude, then filter. The first match sets the mode and stops evaluation. The attribute uses excludeMode; a matching exclude wins even if filter would reject the same node with a different mode. A true filter result never overrides an exclusion.

Example: mixing selectors and a predicate:

await snapdom.toPng(el, {
  exclude: ['.cookie-banner', (node) => node.dataset.secret === 'true'],
  excludeMode: 'remove'
});

For selector-only exclusions, hide keeps the original space:

await snapdom.toPng(el, {
  exclude: ['.cookie-banner', '.tooltip', '[data-test="debug"]']
});

Function-valued rules run on every new capture; an existing result keeps its content. See callbacks and memoization.

Other v2 option changes

When migrating from v2, remove these obsolete settings:

• burst: remove this switch. Eligible repeat memoization is automatic. Use invalidate: true for one fresh capture after an otherwise unobservable change.
• compress: remove the switch. Bitmap optimization is automatic; there is no public opt-out to embed the original resources verbatim.
• resolvePicturePlaceholders and pictureResolver: remove these settings. The clone resolves responsive images and common lazy-loading attributes. There is no replacement tuning object; handle custom loading, concurrency or timeouts in the application before capture.

fast: false remains supported. It now pauses about every frame instead of using idle callbacks; see fast. For removed APIs, TypeScript names and plugin-hook changes, see the migration guide.

outerTransforms

outerTransforms: false removes the captured root's rotation while retaining its scale and skew. Root translation is normalized during capture. Descendant transforms keep their own layout.

• outerTransforms: true (default) keeps the root's rotation and scale/skew, including individual CSS transforms.

outerShadows

• outerShadows: false (default): strips root box-shadow, text-shadow, outline, and drop-shadow(). It preserves filter: blur(), whose bleed is included when the capture is not explicitly clipped.
• outerShadows: true: keeps root shadow/outline/filter effects and expands the bounds for their ink.
• outerShadows: "subtree": also widens the capture for descendant shadow ink outside the root box, bounded by clipping ancestors.

Note: outerShadows: false does not promise a bleed-free box. An explicit clip is the exception: its edges are exact and never expand for bleed.

Example

// Keep root transforms and include root shadow bleed
await snapdom.toSvg(el, { outerTransforms: true, outerShadows: true });

reconcile

With the SVG engine, captured HTML lays out inside <foreignObject>. Inline text and table cells can wrap differently when font metrics or layout constraints differ from the live page.

reconcile: true measures the styled clone offscreen against the live subtree and pins boxes that diverge. It adds a layout pass and can roughly double capture time. Use it when you see wrapping differences; SnapDOM also emits a one-time suggestion for captures that may benefit.

await snapdom.toPng(el, { reconcile: true });

fast

A capture reads the computed style of every node in one pass. On a large tree, such as a data table built from web components, that pass can hold the main thread for hundreds of milliseconds: the page stops painting and responding until it ends.

fast: false lets the capture give the page a turn about every frame, so scrolling, typing and animations continue while it runs. true, the default, captures in one task. The pauses add little to the total time.

fast: 'auto' is experimental and may change: it pauses only once a capture runs past 40 ms, so short captures never pause.

If the captured element changes while a capture is paused, SnapDOM clones it again in one task, so the image shows a state the page really had. That check uses the watchers behind repeat-capture memoization, so a capture that is never memoized (frame-driven trees, function-valued callbacks, captureSelection) keeps what it read.

await snapdom.toPng(table, { fast: false });

Automatic repeat-capture memoization

Capturing the same unchanged element repeatedly would re-walk the tree and re-read every computed style on each call. SnapDOM memoizes eligible static elements from their first capture. Observable DOM, style, media and interaction changes invalidate the result; frame-driven content that cannot be observed reliably is captured fresh. A mutation triggers a conservative full capture, or a differential rebuild when that rebuild is provably equivalent. At most 64 elements stay memoized; the least recently captured one is released.

// Stable captures can reuse the result; the text mutation invalidates it.
for (let i = 0; i < 10; i++) {
  if (i === 3) counter.textContent = 'new value';
  const result = await snapdom(el);
  img.src = (await result.toPng()).src;
}

Frame-driven canvas/video/iframe trees bypass the memo. Programmatic CSSOM edits (stylesheet.insertRule/deleteRule, cssRule.style.* on a rule rather than an element) expose no browser signal, so pass invalidate: true on the next call. That call skips the existing memo and clears style snapshots; a stable fresh result may become the new memo:

sheet.insertRule('.card { color: rebeccapurple }');
await snapdom(el, { invalidate: true });

Callbacks that read application state bypass this reuse; see the cache guide for the supported policies and an example.