zumerlab/snapdom

snapDOM

snapDOM is a fast and accurate DOM-to-image capture tool built for Zumly, a zoom-based view transition framework.

It captures any HTML element as a scalable SVG image, preserving styles, fonts, background images, pseudo-elements, and even shadow DOM. It also supports export to raster image formats and canvas.

• 📸 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

Demo

https://zumerlab.github.io/snapdom/

Installation

NPM / Yarn

1

npm i @zumer/snapdom

1

yarn add @zumer/snapdom

Then import it in your code:

1

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

CDN

1

<script src="https://cdn.jsdelivr.net/npm/@zumer/snapdom/dist/snapdom.min.js"></script>

Script tag (local)

1

<script src="snapdom.js"></script>

ES Module

1

import { snapdom } from './snapdom.mjs';

Module via CDN

1
2
3

<script type="module">
  import { snapdom } from 'https://cdn.jsdelivr.net/npm/@zumer/snapdom/dist/snapdom.mjs';
</script>

Basic usage

Reusable capture

1
2
3
4
5
6
7

const el = document.querySelector('#target');
const result = await snapdom(el, { scale: 2 });

const img = await result.toPng();
document.body.appendChild(img);

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

One-step shortcuts

1
2
3
4
5

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

const blob = await snapdom.toBlob(el);

API

snapdom(el, options?)

Returns an object with reusable export methods:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  url: string;
  toRaw(): string;
  toImg(): Promise<HTMLImageElement>;
  toCanvas(): Promise<HTMLCanvasElement>;
  toBlob(options?): Promise<Blob>;
  toPng(options?): Promise<HTMLImageElement>;
  toJpg(options?): Promise<HTMLImageElement>;
  toWebp(options?): Promise<HTMLImageElement>;
  download(options?): Promise<void>;
}

Shortcut methods

Options

All capture methods accept an options object:

Setting custom dimensions with width and height options

Use the width and height options to generate an image with specific dimensions.

Examples:

1. Fixed width (proportional height) Sets a specific width while maintaining the aspect ratio. Height adjusts proportionally.

1
2
3

const result = await snapdom(element, {
  width: 400 // Outputs a 400px-wide image with auto-scaled height
});

2. Fixed height (proportional width) Sets a specific height while maintaining the aspect ratio. Width adjusts proportionally.

1
2
3

const result = await snapdom(element, {
  height: 200 // Outputs a 200px-tall image with auto-scaled width
});

3. Fixed width and height (may distort image) Forces exact dimensions, potentially distorting the image if the aspect ratio differs.

1
2
3
4

const result = await snapdom(element, {
  width: 800,  // Outputs an 800px × 200px image (may stretch/squish content)
  height: 200
});

Note: If scale is different from 1, it takes priority over width and height. Example: { scale: 3, width: 500 } ignores width and scales the image 3x instead.

Cross-Origin Images

By default, snapDOM loads images with crossOrigin="anonymous" or crossOrigin="use-credentials". In case fails to get the images, useProxy can be used to deal with CORS images:

1
2
3

const result = await snapdom(element, {
  useProxy: 'your/proxy/' //Example: 'https://corsproxy.io/?url=' or 'https://api.allorigins.win/raw?url='
});

Download options

1
2
3
4
5

{
  format?: "svg" | "png" | "jpg" | "jpeg" | "webp"; // default: "png"
  filename?: string;         // default: "capture"
  backgroundColor?: string;  // optional override
}

preCache() – Optional helper

The preCache() function can be used to load external resources (like images and fonts) in advance. It is specially useful when the element to capture is big and complex.

1
2
3

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

await preCache(document.body);

1
2
3
4
5

import { snapdom, preCache } from './snapdom.mjs';
    window.addEventListener('load', async () => {
    await preCache();
    console.log('📦 Resources preloaded');
    });

Options for preCache():

• embedFonts (boolean, default: true) — Inlines non-icon fonts during preload.
• useProxy (string) — Proxy for handling CORS images as fallback.

Features

• Captures shadow DOM and Web Components
• Supports ::before, ::after and ::first-letter pseudo-elements
• Inlines background images and fonts
• Handles Font Awesome, Material Icons, and more
• data-capture="exclude" to ignore an element
• data-capture="placeholder" with data-placeholder-text for masked replacements

Limitations

• External images should be CORS-accessible (use useProxy option for handling CORS denied)
• Iframes are not supported
• When WebP format is used on Safari, it will fallback to PNG rendering.
• @font-face CSS rule is well supported, but if need to use JS FontFace(), see this workaround #43

⚡ Performance Benchmarks

Snapdom has received significant performance improvements since version v1.8.0. The following benchmarks compare:

• Snapdom (current)
• Snapdom v1.8.0
• html2canvas
• html-to-image

Simple elements

Complex elements

Summary

• Snapdom (current) is 2×–6× faster than v1.8.0
• Up to 150× faster than html2canvas
• Up to 8× faster than html-to-image in large scenarios

_{Benchmarks run in Chromium using Vitest.
Hardware: MacBook Air 2018.
⚠️ Performance may vary depending on device.}

Run the benchmarks

1
2
3
4

git clone https://github.com/zumerlab/snapdom.git
cd snapdom
npm install
npm run test:benchmark

Roadmap

Planned improvements for future versions of SnapDOM:

• Implement plugin system SnapDOM will support external plugins to extend or override internal behavior (e.g. custom node transformers, exporters, or filters).

• Refactor to modular architecture Internal logic will be split into smaller, focused modules to improve maintainability and code reuse.

• Decouple internal logic from global options Functions will be redesigned to avoid relying directly on options. A centralized capture context will improve clarity, autonomy, and testability. See next branch

• Expose cache control Users will be able to manually clear image and font caches or configure their own caching strategies.

• Auto font preloading Required fonts will be automatically detected and preloaded before capture, reducing the need for manual preCache() calls.

• Document plugin development A full guide will be provided for creating and registering custom SnapDOM plugins.

• Make export utilities tree-shakeable Export functions like toPng, toJpg, toBlob, etc. will be restructured into independent modules to support tree shaking and minimal builds.

Have ideas or feature requests? Feel free to share suggestions or feedback in GitHub Discussions.

Development

To contribute or build snapDOM locally:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# Clone the repository
git clone https://github.com/zumerlab/snapdom.git
cd snapdom

# Switch to dev branch
git checkout dev

# Install dependencies
npm install

# Compile the library (ESM, CJS, and minified versions)
npm run compile

# Install playwright browsers (necessary for running tests)
npx playwright install

# Run tests
npm test

# Run Benchmarks
npm run test:benchmark

The main entry point is in src/, and output bundles are generated in the dist/ folder.

For detailed contribution guidelines, please see CONTRIBUTING.

Contributors 🙌

💖 Sponsors

Special thanks to @megaphonecolin for supporting this project!

If you’d like to support this project too, you can become a sponsor.

Star History

License

MIT © Zumerlab