{"id":11052,"library":"html2canvas-pro","title":"html2canvas-pro","description":"html2canvas-pro is an actively maintained fork of the popular `niklasvh/html2canvas` library, designed to capture screenshots of web pages or specific DOM elements using JavaScript. It is currently at version 2.0.2 and appears to have a consistent release cadence with several recent patch releases following a major version bump to 2.0.0. Key differentiators include enhanced support for modern CSS color functions like `color()`, `lab()`, `lch()`, `oklab()`, and `oklch()`, improved handling of `object-fit` for images, and explicit control over image smoothing via the `image-rendering` CSS property or a global option. This package aims to address various issues and provide advanced features beyond the original `html2canvas` project, making it suitable for complex screenshot requirements where standard `html2canvas` might fall short. It ships with TypeScript types for improved developer experience.","status":"active","version":"2.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/yorickshan/html2canvas-pro","tags":["javascript","html2canvas","screenshot","typescript"],"install":[{"cmd":"npm install html2canvas-pro","lang":"bash","label":"npm"},{"cmd":"yarn add html2canvas-pro","lang":"bash","label":"yarn"},{"cmd":"pnpm add html2canvas-pro","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { html2canvas } from 'html2canvas-pro';\nconst html2canvas = require('html2canvas-pro');","symbol":"html2canvas","correct":"import html2canvas from 'html2canvas-pro';"},{"note":"Import the `Options` type to define the configuration object passed to the `html2canvas` function, enhancing type safety in TypeScript applications.","symbol":"Options","correct":"import type { Options } from 'html2canvas-pro';"},{"note":"Import the `Canvas` type if you need to specifically type the returned HTMLCanvasElement instance within TypeScript.","symbol":"Canvas","correct":"import type { Canvas } from 'html2canvas-pro';"}],"quickstart":{"code":"import html2canvas from 'html2canvas-pro';\n\n// Capture the entire document body and append it to the DOM\nhtml2canvas(document.body).then(function(canvas) {\n    document.body.appendChild(canvas);\n    console.log('Screenshot of document body appended.');\n\n    // Get the screenshot as a Data URL\n    const dataURL = canvas.toDataURL('image/png');\n    console.log('Partial Data URL:', dataURL.substring(0, 50) + '...');\n});\n\n// Example: Capture a specific element with controlled dimensions and scale\nconst elementToCapture = document.createElement('div');\nelementToCapture.id = 'target-element';\nelementToCapture.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;';\nelementToCapture.textContent = 'Capture me!';\ndocument.body.appendChild(elementToCapture);\n\nhtml2canvas(elementToCapture, {\n    width: 600,  // Target output width\n    height: 300, // Target output height\n    scale: 1,    // Important: set scale to 1 for exact pixel dimensions, ignoring devicePixelRatio\n    backgroundColor: null // Set to null for a transparent background if the source has none\n}).then(scaledCanvas => {\n    const scaledDataURL = scaledCanvas.toDataURL('image/jpeg', 0.8); // Get as JPEG with 80% quality\n    console.log('Scaled screenshot data URL length:', scaledDataURL.length);\n    // Optionally append the scaled canvas as well\n    document.body.appendChild(scaledCanvas);\n    scaledCanvas.style.marginTop = '20px';\n});","lang":"typescript","description":"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."},"warnings":[{"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 });`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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).","error":"Tainted canvases may not be exported."},{"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.","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).","error":"ReferenceError: html2canvas is not defined"},{"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(...) });`","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.","error":"TypeError: Cannot read properties of undefined (reading 'appendChild')"}],"ecosystem":"npm"}