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 html2canvasVerified import paths — ran on the pinned version, not inferred.
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.
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.
For server-side HTML rendering to images, consider headless browser solutions like Puppeteer or Playwright, which offer true rendering capabilities.
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.
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.
Include a Promise polyfill (e.g., `es6-promise`) before loading html2canvas if you need to support older browsers.
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.
Include a Promise polyfill (e.g., `es6-promise` via a script tag or npm import) before initializing html2canvas.
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.
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.