HTML DOM To Image

Convert HTML DOM nodes to images (PNG/JPEG/SVG/Blob). Supports rendering options such as filter, backgroundColor, quality, and pixelRatio.

Convert any HTML DOM node into an image in PNG, JPEG, SVG, or Blob format.

Use Cases

Users request to convert HTML content to an image, take a screenshot of a web page element, generate a PNG/JPEG cover image, or export a specified DOM node as an image file.

Installation

Install html-to-image in the project directory:

bash

npm install html-to-image

Core Workflow

Step 1: Target the DOM Node

Get the HTML element to convert using a selector:

js

const node = document.querySelector('#target-element');

Step 2: Choose Output Format

Format	Function	Description
PNG	toPng(node, options)	Default format, transparency preserved
JPEG	toJpeg(node, { quality: 0.95 })	Compressible, suitable for photos
SVG	toSvg(node, { filter })	Vector format
Blob	toBlob(node)	Binary format, suitable for file downloads

Step 3: Trigger Download

js

htmlToImage.toPng(node, { cacheBust: true })
  .then((dataUrl) => {
    const link = document.createElement('a');
    link.download = 'my-image.png';
    link.href = dataUrl;
    link.click();
  })
  .catch((err) => console.error('oops, something went wrong!', err));

Common Rendering Options

Option	Type	Description
backgroundColor	string	CSS color value, e.g. '#ffffff'
width, height	number	Pixel dimensions to apply to the node before rendering
canvasWidth, canvasHeight	number	Scaling dimensions for the canvas
quality	number	JPEG quality 0~1, default 1.0
cacheBust	boolean	Append a timestamp to disable caching, default false
pixelRatio	number	Pixel ratio; defaults to the device's actual pixel ratio; set to 1 to render at 1x initial scale
filter	function	(node) => boolean, returns true to keep the node

filter Example (Exclude Specific Elements)

js

const filter = (node) => {
  const exclude = ['remove-me', 'secret-div'];
  return !exclude.some(c => node.classList?.contains(c));
};

htmlToImage.toJpeg(node, { quality: 0.95, filter });

React Integration

tsx

import { useCallback, useRef } from 'react';
import { toPng } from 'html-to-image';

const ExportButton = () => {
  const ref = useRef<HTMLDivElement>(null);

  const onClick = useCallback(() => {
    if (!ref.current) return;
    toPng(ref.current, { cacheBust: true })
      .then((dataUrl) => {
        const link = document.createElement('a');
        link.download = 'my-image.png';
        link.href = dataUrl;
        link.click();
      })
      .catch(console.error);
  }, []);

  return (
    <>
      <div ref={ref}>
        {/* Content to convert */}
      </div>
      <button onClick={onClick}>Download Image</button>
    </>
  );
};

Notes

• Including a CORS-tainted <canvas> will cause rendering to fail
• Extremely large DOM nodes may fail due to dataURI length limits
• IE browser is not supported (incompatible with SVG <foreignObject>)