English | 简体中文

SnapDOM

SnapDOM is a next-generation DOM Capture Engine — ultra-fast, modular, and extensible.
It converts any DOM subtree into a self-contained representation that can be exported to SVG, PNG, JPG, WebP, Canvas, Blob, or any custom format through plugins.

* Full DOM capture
* Embedded styles, pseudo-elements, and fonts
* Export to SVG, PNG, JPG, WebP, canvas, or Blob
* ⚡ Ultra fast, no dependencies
* 100% based on standard Web APIs
* Support same-origin ìframe
* Support CSS counter() and CSS counters()
* Support ... line-clamp

Demo

https://snapdom.dev

Table of Contents

- Installation
- NPM / Yarn (stable)
- NPM / Yarn (dev builds)
- CDN (stable)
- CDN (dev builds)
- Build Outputs & Tree-Shaking
- Basic usage
- Reusable capture
- One-step shortcuts
- API
- snapdom(el, options?)
- Shortcut methods
- Options
- Fallback image on load failure
- Dimensions (scale, width, height)
- Cross-Origin Images & Fonts (useProxy)
- Fonts
- embedFonts
- localFonts
- iconFonts
- excludeFonts
- Filtering nodes: exclude vs filter
- outerTransforms
- outerShadows
- Cache control
- preCache
- Plugins (BETA)
- Registering Plugins
- Plugin Lifecycle Hooks
- Context Object
- Custom Exports via Plugins
- Example: Overlay Filter Plugin
- Full Plugin Template
- Limitations
- ⚡ Performance Benchmarks (Chromium)
- Simple elements
- Complex elements
- Run the benchmarks
- Roadmap
- Development
- Contributors 🙌
- 💖 Sponsors
- Star History
- License

Installation

$3

``bash
npm i @zumer/snapdom
yarn add @zumer/snapdom
`

$3

For early access to new features and fixes:

`bash
npm i @zumer/snapdom@dev
yarn add @zumer/snapdom@dev
`

⚠️ The @dev tag usually includes improvements before they reach production, but may be less stable.




$3

`html





`

$3

`html





`

Build Outputs & Tree-Shaking

SnapDOM ships multiple build variants, but using it is simple.

$3

When you import SnapDOM in a project with a bundler:

`js
import { snapdom } from '@zumer/snapdom';
`

your environment automatically loads:

`sh
dist/modules/snapdom.js
`

This is the modular ESM build, enabling:

- Tree-shaking

- Code-splitting

- Lazy loading of exporters (toPng, toJpg, toWebp, etc.)

You do not need to configure anything; bundlers pick this build automatically.

$3

`html


`

This loads the monolithic global build and exposes snapdom on window.




Basic usage

$3


`js
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' });
`

$3


`js
const el = document.querySelector('#target');
const png = await snapdom.toPng(el);
document.body.appendChild(png);

const blob = await snapdom.toBlob(el);
`

API

$3

Returns an object with reusable export methods:

`js
{
url: string;
toRaw(): string;
toImg(): Promise; // deprecated
toSvg(): Promise;
toCanvas(): Promise;
toBlob(options?): Promise;
toPng(options?): Promise;
toJpg(options?): Promise;
toWebp(options?): Promise;
download(options?): Promise;
}
`

$3

| Method | Description |
| ------------------------------ | --------------------------------- |
| snapdom.toImg(el, options?) | Returns an SVG HTMLImageElement (deprecated) |
| snapdom.toSvg(el, options?) | Returns an SVG HTMLImageElement |
| snapdom.toCanvas(el, options?) | Returns a Canvas |
| snapdom.toBlob(el, options?) | Returns an SVG or raster Blob |
| snapdom.toPng(el, options?) | Returns a PNG image |
| snapdom.toJpg(el, options?) | Returns a JPG image |
| snapdom.toWebp(el, options?) | Returns a WebP image |
| snapdom.download(el, options?) | Triggers a download |

Options

> ✅ Note: Style compression is now always on internally. The compress option has been removed.

All capture methods accept an options object:


| Option | Type | Default | Description |
| ----------------- | -------- | -------- | ----------------------------------------------- |
| fast | boolean | true | Skips small idle delays for faster results |
| embedFonts | boolean | false | Inlines non-icon fonts (icon fonts always on) |
| localFonts | array | [] | Local fonts { family, src, weight?, style? } |
| iconFonts | string\|RegExp\|Array | [] | Extra icon font matchers |
| excludeFonts | object | {} | Exclude families/domains/subsets during embedding |
| scale | number | 1 | Output scale multiplier |
| dpr | number | devicePixelRatio | Device pixel ratio |
| width | number | - | Output width |
| height | number | - | Output height |
| backgroundColor | string | "#fff" | Fallback color for JPG/WebP |
| quality | number | 1 | Quality for JPG/WebP (0 to 1) |
| useProxy | string | '' | Proxy base for CORS fallbacks |
| type | string | svg | Default Blob type (svg\|png\|jpg\|webp) |
| exclude | string[] | - | CSS selectors to exclude |
| excludeMode | "hide"\|"remove" | "hide" | How exclude is applied |
| filter | function | - | Custom predicate (el) => boolean |
| filterMode | "hide"\|"remove" | "hide" | How filter is applied |
| cache | string | "soft" | disabled \| soft \| auto \| full |
| placeholders | boolean | true | Show placeholders for images/CORS iframes |
| fallbackURL | string \| function | - | Fallback image for load failure |
| outerTransforms | boolean | true | When false removes translate/rotate but preserves scale/skew, producing a flat, reusable capture |
| outerShadows | boolean | false | Do not expand the root’s bounding box for shadows/blur/outline, and strip those visual effects from the cloned root |

$3

Provide a default image for failed loads. You can pass a fixed URL or a callback that receives measured dimensions and returns a URL (handy to generate dynamic placeholders).

`js
// 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 image also fails to load, snapDOM replaces the with a placeholder block preserving width/height.
- Width/height used by the callback are gathered from the original element (dataset, style/attrs, etc.) when available.




$3

* If scale is provided, it takes precedence over width/height.
* If only width is provided, height scales proportionally (and vice versa).
* Providing both width and height forces an exact size (may distort).

$3

By default snapDOM tries crossOrigin="anonymous" (or use-credentials for same-origin). If an asset is CORS-blocked, you can set useProxy to a prefix URL that forwards the actual src:

`js
await snapdom.toPng(el, {
useProxy: 'https://proxy.corsfix.com/?' // Note: Any cors proxy could be used 'https://proxy.corsfix.com/?'
});
`


* The proxy is only used as a fallback; same-origin and CORS-enabled assets skip it.

$3

#### embedFonts
When true, snapDOM embeds non-icon @font-face rules detected as used within the captured subtree. Icon fonts (Font Awesome, Material Icons, etc.) are embedded always.

#### localFonts
If you serve fonts yourself or have data URLs, you can declare them here to avoid extra CSS discovery:

`js
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:

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

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

`js
await snapdom.toPng(el, {
embedFonts: true,
excludeFonts: {
families: ['Noto Serif', 'SomeHeavyFont'], // skip by family name
domains: ['fonts.gstatic.com', 'cdn.example'], // skip by source host
subsets: ['cyrillic-ext'] // skip by unicode-range subset tag
}
});
`
Notes
- excludeFonts only applies to non-icon fonts. Icon fonts are always embedded.
- Matching is case-insensitive for families. Hosts are matched by substring against the resolved URL.


#### Filtering nodes: exclude vs filter

* exclude: remove by selector.
* excludeMode: hide applies visibility:hidden CSS rule on excluded nodes and the layout remains as the original. remove do not clone excluded nodes at all.
* filter: advanced predicate per element (return false to drop).
* filterMode: hide applies visibility:hidden CSS rule on filtered nodes and the layout remains as the original. remove do not clone filtered nodes at all.

Example: filter out elements with display:none:
`js
/**
* Example filter: skip elements with display:none
* @param {Element} el
* @returns {boolean} true = keep, false = exclude
*/
function filterHidden(el) {
const cs = window.getComputedStyle(el);
if (cs.display === 'none') return false;
return true;
}

await snapdom.toPng(document.body, { filter: filterHidden });
`

Example with exclude: remove banners or tooltips by selector
`js
await snapdom.toPng(el, {
exclude: ['.cookie-banner', '.tooltip', '[data-test="debug"]']
});
`

$3

When capturing rotated or translated elements, you may want use outerTransforms: false option if you want to eliminate those external transforms. So, the output is flat, upright, and ready to use elsewhere.

- outerTransforms: true (default)
Keeps the original transforms and rotate.


$3


- outerShadows: false (default)
Prevents expanding the bounding box for shadows, blur, or outline on the root, and also strips box-shadow, text-shadow, filter: blur()/drop-shadow(), and outline from the cloned root.

> 💡 Tip: Using both (outerTransforms: false + outerShadows: false) produces a strict, minimal bounding box with no visual bleed.

Example

`js
// outerTransforms and remove shadow bleed
await snapdom.toSvg(el, { outerTransforms: true, outerShadows: true });
`

Cache control

SnapDOM maintains internal caches for images, backgrounds, resources, styles, and fonts.
You can control how they are cleared between captures using the cache option:

| Mode | Description |
| ----------- | --------------------------------------------------------------------------- |
| "disabled"| No cache |
| "soft" | Clears session caches (styleMap, nodeMap, styleCache) _(default)_ |
| "auto" | Minimal cleanup: only clears transient maps |
| "full" | Keeps all caches (nothing is cleared, maximum performance) |

Examples:

`js
// Use minimal but fast cache
await snapdom.toPng(el, { cache: 'auto' });

// Keep everything in memory between captures
await snapdom.toPng(el, { cache: 'full' });

// Force a full cleanup on every capture
await snapdom.toPng(el, { cache: 'disabled' });
`

preCache() – Optional helper

Preloads external resources to avoid first-capture stalls (helpful for big/complex trees).

`js
import { preCache } from '@zumer/snapdom';

await preCache({
root: document.body,
embedFonts: true,
localFonts: [{ family: 'Inter', src: '/fonts/Inter.woff2', weight: 400 }],
useProxy: 'https://proxy.corsfix.com/?'
});
`

Plugins (BETA)

SnapDOM includes a lightweight plugin system that allows you to extend or override behavior at any stage of the capture and export process — without touching the core library.

A plugin is a simple object with a unique name and one or more lifecycle hooks.
Hooks can be synchronous or async, and they receive a shared context object.

$3

Global registration (applies to all captures):

`js
import { snapdom } from '@zumer/snapdom';

// You can register instances, factories, or [factory, options]
snapdom.plugins(
myPluginInstance,
[myPluginFactory, { optionA: true }],
{ plugin: anotherFactory, options: { level: 2 } }
);
`

Per-capture registration (only for that specific call):

`js
const out = await snapdom(element, {
plugins: [
[overlayFilterPlugin, { color: 'rgba(0,0,0,0.25)' }],
[myFullPlugin, { providePdf: true }]
]
});
`

* Execution order = registration order (first registered, first executed).
* Per-capture plugins run before global ones.
* Duplicates are automatically skipped by name; a per-capture plugin with the same name overrides its global version.

$3

| Hook | Purpose |
| ------------------------------ | ------------------------------------------------------------------------------------ |
| beforeSnap(context) | Before any clone/style work. Ideal for adjusting global capture options. |
| beforeClone(context) | Before DOM cloning. Can modify live DOM (use carefully). |
| afterClone(context) | After the element subtree has been cloned. Safe to modify styles in the cloned tree. |
| beforeRender(context) | Right before SVG/dataURL serialization. |
| afterRender(context) | After serialization (you can inspect context.svgString or context.dataURL). |
| beforeExport(context) | Before each export call (toPng, toSvg, etc.). |
| afterExport(context, result) | After each export call — can transform the returned result. |
| afterSnap(context) | Runs once, after the first export finishes. Perfect for cleanup. |
| defineExports(context) | Returns a map of custom exporters, e.g. { pdf: async (ctx, opts) => Blob }. |

> Returned values from afterExport are chained to the next plugin (transform pipeline).

$3

Every hook receives a single context object that contains normalized capture state:

* Input & options:
element, debug, fast, scale, dpr, width, height, backgroundColor, quality, useProxy, cache, outerTransforms, outerShadows, embedFonts, localFonts, iconFonts, excludeFonts, exclude, excludeMode, filter, filterMode, fallbackURL.

* Intermediate values (depending on stage):
clone, classCSS, styleCache, fontsCSS, baseCSS, svgString, dataURL.

* During export:
context.export = { type, options, url }
where type is the exporter name ("png", "jpeg", "svg", "blob", etc.), and url is the serialized SVG base.

> You may safely modify context (e.g., override backgroundColor or quality) — but do so early (beforeSnap) for global effects or in beforeExport for single-export changes.




Custom Exports via Plugins

Plugins can add new exports using defineExports(context).
For each export key you return (e.g., "pdf"), SnapDOM automatically exposes a helper method named toPdf() on the capture result.

Register the plugin (global or per capture):

`js
import { snapdom } from '@zumer/snapdom';

// global
snapdom.plugins(pdfExportPlugin());

// or per capture
const out = await snapdom(element, { plugins: [pdfExportPlugin()] });
`

Call the custom export:

`js
const out = await snapdom(document.querySelector('#report'));

// because the plugin returns { pdf: async (ctx, opts) => ... }
const pdfBlob = await out.toPdf({
// exporter-specific options (width, height, quality, filename, etc.)
});
`

$3

Adds a translucent overlay or color filter only to the captured clone (not your live DOM).
Useful for highlighting or dimming sections before export.

`js
/**
* Ultra-simple overlay filter for SnapDOM (HTML-only).
* Inserts a full-size