Registry / web-framework / html2canvas

html2canvas

JSON →
library1.4.1jsnpmunverified

html2canvas is a client-side JavaScript library, currently at stable version 1.4.1, designed to take "screenshots" of webpages or specific DOM elements directly within the user's browser. It operates by reading the Document Object Model (DOM) and applied CSS styles to construct a canvas image, entirely on the client-side, without requiring server-side rendering. A key differentiator is its complete client-side operation, making it suitable for browser-only screenshot needs like generating certificates or tickets. However, it's important to note that it produces a DOM-based representation, which might not be 100% pixel-accurate compared to an actual screenshot, and has limitations regarding unsupported CSS properties. The project maintains a fairly active release cadence, but the README explicitly warns that it is in a "very experimental state" and not recommended for production use, implying potential instability or breaking changes. It is explicitly not suitable for Node.js environments for rendering and requires a proxy for handling cross-origin content.

npm install html2canvas
INSTALL
IMPORT
SIG · HTML2CANVAS
H
html2canvas
web-frameworkjavascriptv1.4.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

html2canvas
import html2canvas from 'html2canvas';
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.

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); });
Debug
Known issues
gotchahtml2canvas 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.
affects: >=1.0.0
gotchaThe 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.
affects: >=1.0.0
gotchaRendering 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.
affects: >=1.0.0
gotchahtml2canvas 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.
affects: >=1.0.0
gotchaThe 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.
affects: <=1.x.x
Errors
Common errors & fixes
Failed to load image <URL>: Cross-origin images are not allowed to be loaded.
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
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
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).
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.
Upgrade
Version history
1.4.1latest on npm
Audit
Dependencies
es6-promiseoptionalRecommended polyfill for Promise support in older browsers.
Agent activity
4 hits · last 30 days
node
4
Resources
html2canvas — npm install html2canvas · libregistry