dom-to-image-more

The domtoimage.impl object exposes the library's internal implementation surface. It is intended for unit tests and advanced integrations and is not part of the stable public API (toSvg, toPng, toJpeg, toBlob, toCanvas, toPixelData). Because it is internal, it may change between releases without notice.

Key components of impl include:

• util: Low-level helpers (type guards, geometry, fetching).
• fontFaces: Web font discovery and inlining.
• images: Image and CSS background inlining.
• inliner: The URL-rewriting engine.
• urlCache: Per-render resource cache.
• options: The live, resolved options for the current/last render.
• copyOptions(options): Normalizes and writes options to impl.options.
• resetUrlCache(): Clears the urlCache.

domtoimage.impl;

impl.urlCache is an array used by the resource fetching core to deduplicate and cache fetches within a single render.

Each entry follows the shape { url: string, promise: Promise | null }. If multiple requests are made for the same URL, they will share the same in-flight or settled promise.

The cache is cleared at the start and end of every render. You can manually clear it using impl.resetUrlCache().

The library requires a browser DOM to function because it reads computed styles and rasterizes via the browser. While it can be imported safely in SSR environments (like Next.js or Angular Universal), calling toPng, toSvg, or other render methods will reject with an a browser DOM is required (SSR) error.

To avoid errors, ensure render calls only execute in the client-side environment using checks like typeof window !== 'undefined' or framework-specific guards (e.g., Angular's isPlatformBrowser).

Install the package using npm:

npm install dom-to-image-more

Then, import or require it in your project depending on your module system:

/* in ES 6 */
import domtoimage from 'dom-to-image-more';

/* in ES 5 */
var domtoimage = require('dom-to-image-more');

Supported Browsers

• Chrome & Firefox: Fully supported. Chrome is recommended for large DOM trees due to better SVG support and CSSStyleDeclaration.cssText support.
• Safari: Not supported due to strict security models on the <foreignObject> tag and flaky image-decode timing. Workaround: Use toSvg and render on the server.
• Internet Explorer: Not supported (lacks SVG <foreignObject> support).

Required JavaScript Features

The library requires modern JavaScript features:

• globalThis (ES2020)
• Promise.prototype.finally (ES2018)

Minimum versions:

• Chrome 71+
• Edge 79+
• Firefox 65+
• Opera 58+
• Safari 12.1+
• Node 12+

The package includes its own type definitions (dom-to-image-more.d.ts), so you do not need to install separate @types packages.

If using esModuleInterop: true in your tsconfig.json, use a standard default import. Otherwise, use the require syntax.

Note: The impl member is typed as unknown to discourage dependency on internal implementation details.

import domtoimage, { Options } from 'dom-to-image-more';

const node = document.getElementById('my-node')!;
const options: Options = { quality: 0.95, styleCaching: 'relaxed' };

domtoimage.toPng(node, options).then((dataUrl: string) => {
    /* ... */
});

To prevent missing glyphs or incorrect metrics, ensure all web fonts and stylesheets are fully loaded before calling a capture method. While the library waits for fonts already being loaded via document.fonts.ready, it cannot wait for new <link rel="stylesheet"> elements added in the same execution tick.

Best Practice: Await document.fonts.ready or listen for the load event on your stylesheet <link> elements before initiating the capture.

By default, nodes with display: none or opacity: 0 are not rendered. However, a node hidden by an ancestor's visibility: hidden is rendered because the library forces the requested root node to be visible.

To render elements that have display: none or opacity: 0 applied directly to them, use the ensureShown option. Note that this does not work if a parent/ancestor is set to display: none; in that case, you must move the node or reveal the ancestor manually.

By default, the library rasterizes at 1× CSS-pixel resolution, which may appear soft on high-DPI/Retina displays. To achieve a crisp, high-resolution capture, pass window.devicePixelRatio to the pixelRatio option.

Note: Browsers have canvas size limits. If the resulting dimensions (width × height × scale × pixelRatio) exceed these limits, the library will clamp the multiplier and log a warning to prevent a blank or partial bitmap.

// Example for crisp Retina output
domtoimage.toPng(node, { pixelRatio: window.devicePixelRatio });