dom-to-svg

Use dom-to-svg to convert an entire HTML document or a specific DOM element into an accessible SVG representation. This is useful for creating high-quality SVG 'screenshots' that work in design tools like Figma or Illustrator because the library avoids using <foreignObject>.

import { documentToSVG, elementToSVG } from 'dom-to-svg'

// Capture the whole document
const svgDocument = documentToSVG(document)

// Capture a specific element
const svgElement = elementToSVG(document.querySelector('#my-element'))

The TraversalContext is an internal object used during the DOM traversal process to maintain state. While typically managed by the library, understanding its properties helps in understanding how the SVG is constructed:

• svgDocument: The XMLDocument being built.
• currentSvgParent: The current SVGElement being processed.
• parentStackingLayer: The current SVGGElement representing the stacking layer.
• stackingLayers: The collection of all StackingLayers.
• ancestorMasks: An array of objects containing mask (SVGMaskElement) and forElement (Element), representing overflow: hidden masks from ancestor elements.
• labels: A Map linking HTMLLabelElement to their string values.
• getUniqueId: A function to generate unique IDs with a specific prefix.
• options: The resolved DomToSvgOptions.

The output of documentToSVG or elementToSVG is an SVG DOM document. To obtain the raw SVG string (for saving to a file or passing to other tools), use the standard XMLSerializer API.

import { documentToSVG } from 'dom-to-svg'

const svgDocument = documentToSVG(document)
const svgString = new XMLSerializer().serializeToString(svgDocument)

By default, the generated SVG may reference external resources like fonts or images. To make the SVG self-contained and portable, use inlineResources to convert these external assets into data: URIs within the SVG document.

import { inlineResources } from 'dom-to-svg'

// Inline external resources (fonts, images, etc) as data: URIs
await inlineResources(svgDocument.documentElement)

When using dom-to-svg, you can provide a DomToSvgOptions object to control the output.

• captureArea: A DOMRectReadOnly that defines the visual area to constrain the SVG to. Elements that do not intersect this area will be excluded from the resulting SVG.
• keepLinks: A boolean that determines whether <a> tags are included in the SVG to maintain interactivity. Defaults to true.

const options: DomToSvgOptions = {
  captureArea: { x: 0, y: 0, width: 500, height: 500 },
  keepLinks: true
};

Use the parse function to convert a CSS gradient string into an array of Gradient nodes. Each node in the returned array represents a parsed gradient structure, including its type, orientation, and color stops.

import { parse } from 'dom-to-svg'; // Note: Import path depends on your installation

const gradients = parse('linear-gradient(to right, red, blue)');

Use documentToSVG(document, options?) to convert an entire Document into an XMLDocument containing an SVG representation. This is a convenience wrapper around elementToSVG that targets the document.documentElement.

import { documentToSVG } from 'dom-to-svg';

const svgDocument = documentToSVG(document);
const svgString = new XMLSerializer().serializeToString(svgDocument);

Use elementToSVG(element, options?) to convert a specific DOM Element into an XMLDocument containing an SVG representation.

The function performs the following:

• Creates a new SVG document with appropriate namespaces (xmlns and xmlns:xlink).
• Injects a comment indicating the source URL.
• Attempts to copy and resolve @font-face rules from the element's owner document to ensure fonts are preserved.
• Traverses the element tree to build the SVG structure.
• Sets the width, height, and viewBox attributes based on the element's bounding box or the provided captureArea.

import { elementToSVG } from 'dom-to-svg';

const element = document.querySelector('#my-element');
const svgDocument = elementToSVG(element);

// To get the SVG string:
const svgString = new XMLSerializer().serializeToString(svgDocument);

A ColorStop represents an individual color within a gradient's colorStops array. It can be one of the following types:

• LiteralNode: A named color (e.g., value: 'red').
• HexNode: A hex color without the pound sign (e.g., value: 'ff0000').
• RgbNode: An RGB color tuple (e.g., value: [255, 0, 0]).
• RgbaNode: An RGBA color tuple (e.g., value: [255, 0, 0, 1]).

export type ColorStop = LiteralNode | HexNode | RgbNode | RgbaNode

The parse function returns an array of Gradient objects. A Gradient can be one of the following types:

• LinearGradientNode: A standard linear gradient.
• RepeatingLinearGradientNode: A repeating linear gradient.
• RadialGradientNode: A radial gradient.
• RepeatingRadialGradientNode: A repeating radial gradient.

export type Gradient =
	| LinearGradientNode
	| RadialGradientNode
	| RepeatingLinearGradientNode
	| RepeatingRadialGradientNode