html2canvas

Common errors

• Failed to load image <URL>: Cross-origin images are not allowed to be loaded.

  cause Attempting to render a DOM element containing images from a different origin without a proxy or CORS headers.
  fix Ensure cross-origin images are served with appropriate CORS headers or configure a proxy server to fetch and serve them from the same origin as your application, then specify the `proxy` option in html2canvas. Options like `allowTaint: true` and `useCORS: true` can help but do not bypass the fundamental Same-Origin Policy.

• ReferenceError: Promise is not defined

  cause Running html2canvas in an environment (typically an older browser like IE11) that does not natively support JavaScript Promises.
  fix Include a Promise polyfill (e.g., `es6-promise` via a script tag or npm import) before initializing html2canvas.

• Module 'html2canvas' is not ESM

  cause This error can occur when importing `html2canvas` in an ESM context within a Node.js environment where it's not correctly transpiled or configured for server-side usage, despite `package.json`'s `engines` field allowing Node.js installation.
  fix html2canvas is not designed for rendering in Node.js. If you encounter this when trying to bundle for the browser, ensure your bundler (Webpack, Rollup, Parcel) is correctly configured to handle the library's module format for browser consumption. For server-side screenshot needs, use a headless browser solution.

• The generated canvas image does not perfectly match the webpage's appearance (e.g., missing shadows, incorrect fonts, misaligned elements).

  cause html2canvas's DOM-based rendering mechanism has limitations and does not support all CSS properties and rendering intricacies of a browser's native rendering engine. Specific unsupported properties include `box-shadow`, `filter`, and certain `transform` effects.
  fix Consult the html2canvas 'Features' documentation for a list of supported and unsupported CSS properties. Adjust your CSS to use supported properties where possible, or accept that certain complex visual effects may not render identically.

Warnings

• gotcha html2canvas is explicitly stated to be in a 'very experimental state' in the official README, despite its active maintenance. This implies that APIs or internal behavior might change significantly between versions, and it may not be fully production-ready in terms of stability or comprehensive feature support. Users should test thoroughly and anticipate potential breaking changes or limitations.
  Fix: Refer to the official documentation and GitHub discussions for the latest updates and known issues before deploying to production. Pin exact versions in your package.json.
• gotcha The library is designed for client-side browser usage and is 'not suitable' for use in Node.js environments for rendering. While it can be installed via npm, attempting to use its core rendering functionality server-side will fail.
  Fix: For server-side HTML rendering to images, consider headless browser solutions like Puppeteer or Playwright, which offer true rendering capabilities.
• gotcha Rendering cross-origin content (e.g., images, iframes) directly will fail due to browser Same-Origin Policy restrictions. html2canvas does not circumvent these policies and requires a proxy server to load such content.
  Fix: Implement a server-side proxy to fetch cross-origin resources and serve them from the same origin as your application. Configure the `proxy` option in html2canvas.
• gotcha html2canvas creates a screenshot based on the DOM structure and computed styles, not an actual pixel-by-pixel render. This means the output may not be 100% accurate to the visual representation in the browser, especially for complex CSS properties like `box-shadow`, `filter`, or certain transforms, which may not be fully supported.
  Fix: Review the list of supported CSS properties in the html2canvas documentation. Simplify complex styling where possible or accept minor visual discrepancies. Test rendering thoroughly across target browsers.
• gotcha The library utilizes JavaScript Promises and expects them to be available globally. Older browsers (e.g., IE9-IE11) lack native Promise support.
  Fix: Include a Promise polyfill (e.g., `es6-promise`) before loading html2canvas if you need to support older browsers.

Install

• npm install html2canvas npm
• yarn add html2canvas yarn
• pnpm add html2canvas pnpm

Imports

• html2canvas
  wrong:

  import { html2canvas } from 'html2canvas';

  correct:

  import html2canvas from 'html2canvas';

  The primary function `html2canvas` is typically consumed as a default import in ESM environments.
• html2canvas

  const html2canvas = require('html2canvas');

  For CommonJS environments or older Node.js bundlers, `require` can be used. Note that html2canvas is not suitable for rendering in Node.js, only for bundling purposes.
• html2canvas

  <script src="https://cdn.jsdelivr.net/npm/html2canvas@1.4.1/dist/html2canvas.min.js"></script>
  <script>
    html2canvas(document.body).then(canvas => {
      // ...
    });
  </script>

  When included directly via a script tag in the browser, `html2canvas` becomes available as a global function.

Quickstart

This quickstart demonstrates how to import and use html2canvas to capture the entire document body, convert it to an image, and append it to the page. It includes basic options for cross-origin content handling and logging.

import html2canvas from 'html2canvas';

const captureAndDisplayBody = async () => {
  const bodyElement = document.body;

  try {
    const canvas = await html2canvas(bodyElement, {
      allowTaint: true, // Set to true if you are handling tainted canvases (e.g., cross-origin images without proxy)
      useCORS: true,    // Attempt to load images using CORS
      logging: true     // Enable logging for debugging
    });

    // Create an image element from the canvas
    const img = document.createElement('img');
    img.src = canvas.toDataURL('image/png');
    img.alt = 'Screenshot of the page body';
    img.style.maxWidth = '100%';
    img.style.border = '2px solid blue';
    
    // Append the image to the document or a specific container
    document.getElementById('screenshot-container')?.appendChild(img);
    console.log('Screenshot captured and displayed successfully!');

  } catch (error) {
    console.error('Error capturing screenshot:', error);
  }
};

// Example of triggering the capture (e.g., on a button click or after DOM load)
document.addEventListener('DOMContentLoaded', () => {
  const button = document.createElement('button');
  button.textContent = 'Take Screenshot of Body';
  button.onclick = captureAndDisplayBody;
  document.body.prepend(button);

  const container = document.createElement('div');
  container.id = 'screenshot-container';
  document.body.appendChild(container);
});