html2canvas-pro

Common errors

• Tainted canvases may not be exported.

  cause An attempt was made to export a canvas that contains content loaded from a different origin (e.g., an image without proper CORS headers or a cross-origin iframe).
  fix Ensure all images and resources within the captured element are served from the same domain or configured with CORS headers. Set `useCORS: true` in the `html2canvas` options if resources have valid CORS headers. Consider using a proxy to fetch cross-origin images if direct CORS is not possible.

• ReferenceError: html2canvas is not defined

  cause The `html2canvas` function was called before the library was properly loaded or imported, or it was imported incorrectly (e.g., using named import for a default export).
  fix Verify that `import html2canvas from 'html2canvas-pro';` is at the top of your module. If using CommonJS, ensure `const html2canvas = require('html2canvas-pro');` is used. In a browser environment without a bundler, confirm the script tag for `html2canvas-pro` is correctly included and loaded before the function is called.

• TypeError: Cannot read properties of undefined (reading 'appendChild')

  cause The target element passed to `html2canvas` (e.g., `document.body`) or the element to which the canvas is appended is `null` or `undefined`, often because the script runs before the DOM is fully loaded.
  fix Wrap your `html2canvas` call in a DOMContentLoaded listener or ensure it runs after the target element is guaranteed to exist in the DOM. For example: `document.addEventListener('DOMContentLoaded', () => { html2canvas(document.body).then(...) });`

Warnings

• gotcha By default, the output canvas dimensions are affected by the browser's `devicePixelRatio`. This can lead to larger canvas sizes than expected based on element dimensions.
  Fix: To achieve exact pixel dimensions for the output canvas, specify both `width` and `height` options in the configuration object and set `scale: 1`. Example: `html2canvas(element, { width: 1920, height: 1080, scale: 1 });`
• gotcha Capturing content from different origins (e.g., images, iframes hosted on another domain) will 'taint' the canvas, preventing its content from being read or exported due to browser security restrictions (CORS).
  Fix: Ensure all assets (images, fonts) are served from the same origin as the page. If cross-origin resources must be used, they require appropriate CORS headers (`Access-Control-Allow-Origin`) and the `useCORS: true` option. For iframes, they must be same-origin and iframed with the `allow-same-origin` sandbox attribute.

Install

• npm install html2canvas-pro npm
• yarn add html2canvas-pro yarn
• pnpm add html2canvas-pro pnpm

Imports

• html2canvas
  wrong:

  import { html2canvas } from 'html2canvas-pro';
  const html2canvas = require('html2canvas-pro');

  correct:

  import html2canvas from 'html2canvas-pro';

  The library primarily uses a default export for its main function. While CommonJS `require` might work in some bundler setups, ESM `import` is the idiomatic way for modern JavaScript and TypeScript projects.
• Options

  import type { Options } from 'html2canvas-pro';

  Import the `Options` type to define the configuration object passed to the `html2canvas` function, enhancing type safety in TypeScript applications.
• Canvas

  import type { Canvas } from 'html2canvas-pro';

  Import the `Canvas` type if you need to specifically type the returned HTMLCanvasElement instance within TypeScript.

Quickstart

Demonstrates how to capture a screenshot of the document body or a specific element, append the generated canvas to the DOM, and control output dimensions and image format.

import html2canvas from 'html2canvas-pro';

// Capture the entire document body and append it to the DOM
html2canvas(document.body).then(function(canvas) {
    document.body.appendChild(canvas);
    console.log('Screenshot of document body appended.');

    // Get the screenshot as a Data URL
    const dataURL = canvas.toDataURL('image/png');
    console.log('Partial Data URL:', dataURL.substring(0, 50) + '...');
});

// Example: Capture a specific element with controlled dimensions and scale
const elementToCapture = document.createElement('div');
elementToCapture.id = 'target-element';
elementToCapture.style.cssText = 'width: 300px; height: 150px; background-color: #e0f7fa; border: 2px solid #00bcd4; margin-top: 20px; display: flex; align-items: center; justify-content: center; font-family: sans-serif;';
elementToCapture.textContent = 'Capture me!';
document.body.appendChild(elementToCapture);

html2canvas(elementToCapture, {
    width: 600,  // Target output width
    height: 300, // Target output height
    scale: 1,    // Important: set scale to 1 for exact pixel dimensions, ignoring devicePixelRatio
    backgroundColor: null // Set to null for a transparent background if the source has none
}).then(scaledCanvas => {
    const scaledDataURL = scaledCanvas.toDataURL('image/jpeg', 0.8); // Get as JPEG with 80% quality
    console.log('Scaled screenshot data URL length:', scaledDataURL.length);
    // Optionally append the scaled canvas as well
    document.body.appendChild(scaledCanvas);
    scaledCanvas.style.marginTop = '20px';
});