{"id":11051,"library":"html2canvas","title":"html2canvas","description":"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.","status":"active","version":"1.4.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/niklasvh/html2canvas","tags":["javascript","typescript"],"install":[{"cmd":"npm install html2canvas","lang":"bash","label":"npm"},{"cmd":"yarn add html2canvas","lang":"bash","label":"yarn"},{"cmd":"pnpm add html2canvas","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Recommended polyfill for Promise support in older browsers.","package":"es6-promise","optional":true}],"imports":[{"note":"The primary function `html2canvas` is typically consumed as a default import in ESM environments.","wrong":"import { html2canvas } from 'html2canvas';","symbol":"html2canvas","correct":"import html2canvas from 'html2canvas';"},{"note":"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.","symbol":"html2canvas","correct":"const html2canvas = require('html2canvas');"},{"note":"When included directly via a script tag in the browser, `html2canvas` becomes available as a global function.","symbol":"html2canvas","correct":"<script src=\"https://cdn.jsdelivr.net/npm/html2canvas@1.4.1/dist/html2canvas.min.js\"></script>\n<script>\n  html2canvas(document.body).then(canvas => {\n    // ...\n  });\n</script>"}],"quickstart":{"code":"import html2canvas from 'html2canvas';\n\nconst captureAndDisplayBody = async () => {\n  const bodyElement = document.body;\n\n  try {\n    const canvas = await html2canvas(bodyElement, {\n      allowTaint: true, // Set to true if you are handling tainted canvases (e.g., cross-origin images without proxy)\n      useCORS: true,    // Attempt to load images using CORS\n      logging: true     // Enable logging for debugging\n    });\n\n    // Create an image element from the canvas\n    const img = document.createElement('img');\n    img.src = canvas.toDataURL('image/png');\n    img.alt = 'Screenshot of the page body';\n    img.style.maxWidth = '100%';\n    img.style.border = '2px solid blue';\n    \n    // Append the image to the document or a specific container\n    document.getElementById('screenshot-container')?.appendChild(img);\n    console.log('Screenshot captured and displayed successfully!');\n\n  } catch (error) {\n    console.error('Error capturing screenshot:', error);\n  }\n};\n\n// Example of triggering the capture (e.g., on a button click or after DOM load)\ndocument.addEventListener('DOMContentLoaded', () => {\n  const button = document.createElement('button');\n  button.textContent = 'Take Screenshot of Body';\n  button.onclick = captureAndDisplayBody;\n  document.body.prepend(button);\n\n  const container = document.createElement('div');\n  container.id = 'screenshot-container';\n  document.body.appendChild(container);\n});","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For server-side HTML rendering to images, consider headless browser solutions like Puppeteer or Playwright, which offer true rendering capabilities.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Include a Promise polyfill (e.g., `es6-promise`) before loading html2canvas if you need to support older browsers.","message":"The library utilizes JavaScript Promises and expects them to be available globally. Older browsers (e.g., IE9-IE11) lack native Promise support.","severity":"gotcha","affected_versions":"<=1.x.x"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to render a DOM element containing images from a different origin without a proxy or CORS headers.","error":"Failed to load image <URL>: Cross-origin images are not allowed to be loaded."},{"fix":"Include a Promise polyfill (e.g., `es6-promise` via a script tag or npm import) before initializing html2canvas.","cause":"Running html2canvas in an environment (typically an older browser like IE11) that does not natively support JavaScript Promises.","error":"ReferenceError: Promise is not defined"},{"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.","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.","error":"Module 'html2canvas' is not ESM"},{"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.","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.","error":"The generated canvas image does not perfectly match the webpage's appearance (e.g., missing shadows, incorrect fonts, misaligned elements)."}],"ecosystem":"npm"}