`util` reference

Internal utility helpers used throughout dom-to-image-more. They are exposed for testing and advanced integration via:

domtoimage.impl.util;

⚠️ These are implementation details, not part of the stable public API (toSvg, toPng, toJpeg, toBlob, toCanvas, toPixelData). They may change between releases. They are documented here because the test suite and some advanced callers depend on them.

The object is produced by newUtil() in src/dom-to-image-more.js and attached to domtoimage.impl.util. For the rest of the impl surface (fontFaces, images, inliner, urlCache, options, copyOptions), see IMPL.md.

Type guards

All of these return a boolean and are built on isInstanceOf, which checks the value against the constructor from both its own window and the parent window (so they work correctly across <iframe> boundaries).

Function	Returns `true` when the value is…
`isElement(value)`	a DOM `Element`
`isHTMLElement(value)`	an `HTMLElement`
`isHTMLCanvasElement(value)`	an `HTMLCanvasElement`
`isHTMLImageElement(value)`	an `HTMLImageElement`
`isHTMLInputElement(value)`	an `HTMLInputElement`
`isHTMLLinkElement(value)`	an `HTMLLinkElement`
`isHTMLScriptElement(value)`	an `HTMLScriptElement`
`isHTMLStyleElement(value)`	an `HTMLStyleElement`
`isHTMLTextAreaElement(value)`	an `HTMLTextAreaElement`
`isSVGElement(value)`	an `SVGElement`
`isSVGImageElement(value)`	an `SVGImageElement` (a nested SVG `<image>`, whose `href`/`xlink:href` is inlined)
`isSVGSVGElement(value)`	an `SVGSVGElement` (an `<svg>` root; non-root SVG elements take a different render path)
`isSVGRectElement(value)`	an `SVGRectElement`
`isSVGUseElement(value)`	an `SVGUseElement` (a `<use>` referencing an element to inline)
`isShadowRoot(value)`	a `ShadowRoot`
`isInShadowRoot(value)`	a node whose root (`getRootNode()`) is a `ShadowRoot`. Safe for `null`/`undefined` and for nodes without `getRootNode`.
`isElementHostForOpenShadowRoot(value)`	an `Element` that hosts an open shadow root (`value.shadowRoot !== null`)
`isShadowSlotElement(value)`	an `HTMLSlotElement` that lives inside a shadow root

`isInstanceOf(value, typeName)`

(value: any, typeName: string) => boolean

Cross-realm instanceof check. Resolves the constructor named typeName from the value's own window and window.parent, returning true if the value is an instance of either. This is the primitive that all the guards above are built on, so type checks survive elements that originate inside iframes.

`isDataUrl(url)`

(url: string) => boolean

true if the string begins with data:.

`isDimensionMissing(value)`

(value: number) => boolean

true when a measured dimension is unusable — i.e. NaN, 0, or negative. Used to decide when to fall back to default sizing (e.g. width="100%").

Geometry / dimensions

`width(node)`

(node: Element) => number

Computed pixel width of node. Reads the CSS width via getComputedStyle; if that is not a px value, falls back to scrollWidth + border-left-width + border-right-width.

`height(node)`

(node: Element) => number

Computed pixel height of node. Same strategy as width, using scrollHeight + border-top-width + border-bottom-width as the fallback.

Note: both read live layout, so the value depends on the element's current rendered state (scrollbars, etc.).

Window / document

`getWindow(node)`

(node?: Node) => Window

Returns the Window that owns node (node.ownerDocument.defaultView), falling back to window, then global, then globalThis. Each fallback is typeof-guarded so it does not throw under SSR (Angular Universal, Next.js, plain Node) where window/global may be absent. Tolerates a missing/undefined node. Underpins the cross-realm type guards.

URLs & resources

`resolveUrl(url, baseUrl)`

(url: string, baseUrl: string) => string

Resolves a possibly relative url against baseUrl and returns the absolute URL. Implemented by letting the browser normalize an <a href> inside a throwaway document that has a <base> set to baseUrl.

`getAndEncode(url, type)`

(url: string, type?: ResourceType) => Promise<string>

Thin wrapper over the shared fetch core (see below) that resolves to a data URL (base64) — used at the inline sites (images, fonts). type is the resource kind (a domtoimage.ResourceType value: IMAGE, CSS_IMAGE, FONT, STYLESHEET) used by requestInterceptor and to scope imagePlaceholder; it defaults to undefined. Resolves to '' when the resource is dropped.

`getResourceText(url, type, allowNetwork)`

(url: string, type?: ResourceType, allowNetwork?: boolean) => Promise<string | null>

Sibling wrapper that resolves to the resource's text (via readAsText, no base64 round-trip) — used to load external stylesheets (loadExternalStyleSheet). allowNetwork === false consults requestInterceptor but performs no network fetch (so a readable or not-opted-in stylesheet can still be supplied by the interceptor without being downloaded). Resolves to null when there's no resource.

Shared fetch core

Both wrappers share one fetch core that returns a Blob (network), a data URL string (supplied by requestInterceptor/imagePlaceholder), or null (dropped); the wrappers handle the encode/decode, so a resource is only base64-encoded where it's actually inlined. Key behaviors:

Caches by URL in domtoimage.impl.urlCache; concurrent/repeat requests for the same URL share one promise. Reset with resetUrlCache().
requestInterceptor is consulted first, before the fetch: requestInterceptor(url, { type, status: undefined }) may return a data URL (or a promise of one) to short-circuit the network.
Honors options: cacheBust, httpTimeout, useCredentials / useCredentialsFilters, and corsImg (proxy URL/method/headers/data with the #{cors} token substituted).
Treats HTTP status 0 as success for file:// URLs (Firefox local-file quirk).
On any failure (network/timeout/non-2xx, or a response that isn't a usable Blob): consults requestInterceptor(url, { type, status }) for a recovery value (takes precedence), then imagePlaceholder — only for image types (IMAGE / CSS_IMAGE; a FONT/STYLESHEET, or an untyped call, drops) — then drops. Never rejects; every failure is surfaced via onImageError.

`makeImage(uri)`

(uri: string) => Promise<HTMLImageElement | undefined>

Loads uri into an Image (wrapped in an offscreen <svg> appended to document.body) and resolves once it has loaded. Returns undefined for the empty data URL data:,. Applies crossOrigin = 'use-credentials' when the useCredentials option is set. Removes the temporary node on load/error; before resolving it awaits image.decode() (when available) and then one requestAnimationFrame, so the bitmap is fully decoded before a canvas reads it — guarding the Firefox/Safari blank-render timing race (issues #146, #192).

`canvasToBlob(canvas)`

(canvas: HTMLCanvasElement) => Promise<Blob>

Resolves to a PNG Blob of the canvas. Uses the native canvas.toBlob when available, otherwise a manual toDataURL → atob → Uint8Array → Blob fallback.

String helpers

`escape(string)`

(string: string) => string

Exposed as util.escape (implementation escapeRegEx).

Escapes characters that are special in a regular expression (. * + ? ^ $ { } ( ) | [ ] / \) so the string can be used as a regex literal.

`escapeXhtml(string)`

(string: string) => string

Escapes a string for safe embedding in the XHTML/foreignObject payload of the generated SVG: replaces % → %25, # → %23, and newlines → %0A.

Misc

`asArray(arrayLike)`

(arrayLike: ArrayLike<T>) => T[]

Converts an array-like (e.g. a NodeList or CSSStyleDeclaration) into a real Array by index copy.

`uid()`

() => string

Returns a short unique id of the form u<4-random-base36-chars><counter> (e.g. u3f9a0). The incrementing counter guarantees uniqueness within a session even if the random part collides.

Quick index

Name	Category	Returns
`isElement`	type guard	`boolean`
`isElementHostForOpenShadowRoot`	type guard	`boolean`
`isShadowRoot`	type guard	`boolean`
`isInShadowRoot`	type guard	`boolean`
`isHTMLElement`	type guard	`boolean`
`isHTMLCanvasElement`	type guard	`boolean`
`isHTMLInputElement`	type guard	`boolean`
`isHTMLImageElement`	type guard	`boolean`
`isHTMLLinkElement`	type guard	`boolean`
`isHTMLScriptElement`	type guard	`boolean`
`isHTMLStyleElement`	type guard	`boolean`
`isHTMLTextAreaElement`	type guard	`boolean`
`isShadowSlotElement`	type guard	`boolean`
`isSVGElement`	type guard	`boolean`
`isSVGImageElement`	type guard	`boolean`
`isSVGSVGElement`	type guard	`boolean`
`isSVGRectElement`	type guard	`boolean`
`isSVGUseElement`	type guard	`boolean`
`isInstanceOf`	type guard	`boolean`
`isDataUrl`	type guard	`boolean`
`isDimensionMissing`	dimensions	`boolean`
`width`	dimensions	`number`
`height`	dimensions	`number`
`getWindow`	window	`Window`
`resolveUrl`	url	`string`
`getAndEncode`	url, type?	`Promise<string>`
`getResourceText`	url, type?, allowNetwork?	`Promise<string \| null>`
`makeImage`	url	`Promise<HTMLImageElement \| undefined>`
`canvasToBlob`	url	`Promise<Blob>`
`escape`	string	`string`
`escapeXhtml`	string	`string`
`asArray`	misc	`Array`
`uid`	misc	`string`

FilesExpand file tree

UTILS.md

Latest commit

History

UTILS.md

File metadata and controls

util reference

Type guards

isInstanceOf(value, typeName)

isDataUrl(url)

isDimensionMissing(value)

Geometry / dimensions

width(node)

height(node)

Window / document

getWindow(node)