Configuration Options

This document outlines all available configuration options for html2canvas-pro. These options allow you to customize the rendering behavior, image handling, and output of the canvas.

Basic Configuration

Option Name	Default	Description	Example
allowTaint	false	Whether to allow cross-origin images to taint the canvas	true
backgroundColor	#ffffff	Canvas background color, if none is specified in DOM. Set null for transparent	"rgba(0,0,0,0.5)"
canvas	null	Existing canvas element to use as a base for drawing on	document.createElement('canvas')
logging	true	Enable logging for debug purposes	false
removeContainer	true	Whether to cleanup the cloned DOM elements html2canvas-pro creates temporarily	false
scale	window.devicePixelRatio	The scale to use for rendering. Controls the canvas internal resolution. Defaults to the browser's device pixel ratio (usually 1 or 2). Higher values produce sharper images but larger file sizes	2 or 1
width	Element width	The CSS display width of the canvas. The actual canvas pixel width will be width × scale. See Canvas Dimensions below	1200
height	Element height	The CSS display height of the canvas. The actual canvas pixel height will be height × scale. See Canvas Dimensions below	800

Canvas Dimensions

⚠️ Important: Understanding how width, height, and scale work together:

• Canvas Display Size = width × height (CSS pixels, how it appears on screen)
• Canvas Internal Resolution = (width × scale) × (height × scale) (actual pixels stored in canvas)

Example:

// This configuration:
html2canvas(element, {
    width: 1920,
    height: 1080
});

// On a device with devicePixelRatio = 2 (e.g., Retina display):
// Will produce a canvas with:
// - Display size: 1920px × 1080px
// - Internal resolution: 3840px × 2160px (1920×2, 1080×2)
// - Canvas attributes: width="3840" height="2160"
// - Canvas style: width: 1920px; height: 1080px;

To get exact pixel dimensions:

// If you want the canvas to be EXACTLY 1920×1080 pixels:
html2canvas(element, {
    width: 1920,
    height: 1080,
    scale: 1  // Set scale to 1 for exact dimensions
});

// This will produce:
// - Display size: 1920px × 1080px  
// - Internal resolution: 1920px × 1080px
// - Canvas attributes: width="1920" height="1080"

Why does scale default to devicePixelRatio?

This produces high-quality images on high-DPI screens (like Retina displays). If you don't need the extra quality or want to control the exact output dimensions, set scale: 1.

Image Handling

Options that control how images are processed and loaded.

Option Name	Default	Description	Example
customIsSameOrigin	null	Custom function to determine if an image URL is same-origin. Accepts two parameters: (src: string, oldFn: (src: string) => boolean) => boolean | Promise<boolean> where src is the image URL and oldFn is the default same-origin check function	See examples below
imageSmoothing	true	Whether to apply smoothing to images. Set to false for pixel-perfect rendering of pixel art, sprites, and low-res images. Also respects CSS image-rendering property	false
imageSmoothingQuality	browser default	Quality level for image smoothing when imageSmoothing is enabled: 'low', 'medium', or 'high'. Higher quality may be slower for large images	'high'
imageTimeout	15000	Timeout for loading an image (in milliseconds). Set to 0 to disable timeout	30000
maxCacheSize	100	Maximum number of image resources kept in the internal LRU cache (max 10000)	500
proxy	null	Url to the proxy which is to be used for loading cross-origin images. If left empty, cross-origin images won't be loaded	"https://proxy.example.com/"
useCORS	false	Whether to attempt to load images from a server using CORS	true

Rendering Control

Options that control how the content is rendered to the canvas.

Option Name	Default	Description	Example
foreignObjectRendering	false	Whether to use ForeignObject rendering if the browser supports it	true
ignoreElements	(element) => false	Predicate function which removes the matching elements from the render	(el) => el.classList.contains('no-capture')
iframeContainer	null	Custom parent node for the temporary iframe container. Useful for Shadow DOM scenarios. If not provided, will auto-detect Shadow Root or use document.body	document.querySelector('#my-shadow-host').shadowRoot
onclone	null	Callback function which is called when the Document has been cloned for rendering, can be used to modify the contents that will be rendered without affecting the original source document	(doc) => doc.querySelector('.date').textContent = new Date().toISOString()
x	Element x-offset	Crop canvas x-coordinate	10
y	Element y-offset	Crop canvas y-coordinate	20
scrollX	Element scrollX	The x-scroll position to use when rendering element (for example if the Element uses position: fixed)	0
scrollY	Element scrollY	The y-scroll position to use when rendering element (for example if the Element uses position: fixed)	100
windowWidth	Window.innerWidth	Window width to use when rendering Element, which may affect things like Media queries	1920
windowHeight	Window.innerHeight	Window height to use when rendering Element, which may affect things like Media queries	1080

Element Exclusion

If you wish to exclude certain Elements from getting rendered, you can add a data-html2canvas-ignore attribute to those elements and html2canvas-pro will exclude them from the rendering.

<div>
  This will be rendered
  <div data-html2canvas-ignore>This will NOT be rendered</div>
</div>

Advanced Options

Option Name	Default	Description	Example
cspNonce	null	Content-Security-Policy nonce for inline styles	"abc123"
normalizeDom	true	Normalize the cloned DOM before capture (disable animations, reset transforms). Set to false to preserve the original DOM state	false
skipValidation	false	Skip the built-in input validation (not recommended)	true
enablePerformanceMonitoring	false	Enable performance metrics collection and log a timing summary. Defaults to the logging option value when not specified	true
signal	null	AbortSignal to cancel an in-progress render	new AbortController().signal
validator	default	Custom Validator instance for input validation	createStrictValidator(['proxy.example.com'])

Error Handling & Cancellation

Use onError to observe failed resources and signal to cancel an in-progress render:

const controller = new AbortController();

html2canvas(element, {
    onError: (error) => {
        // A resource (image, font, …) failed to load.
        // The render continues — this is a notification hook, not an abort.
        console.warn('Resource failed:', error);
    },
    signal: controller.signal
}).then(canvas => {
    document.body.appendChild(canvas);
});

// Cancel the in-progress capture; the promise rejects with an `AbortError`:
controller.abort();

Progress Callback

Subscribe to pipeline milestones with onProgress:

import html2canvas from 'html2canvas-pro';

html2canvas(element, {
    onProgress: (phase, progress) => {
        console.log(`${phase}: ${progress}%`);
        // clone 10 → clone 30 → parse 50 →
        // preload 50…60 (one event per settled image batch) →
        // layout 60 → render 90 → render 100
    }
});

phase is one of 'clone', 'parse', 'preload', 'layout' or 'render'; progress is a coarse 0–100 estimate. Image preloading reports one event per settled batch across the 50–60 range, so captures with many images show incremental progress. Callback exceptions are caught and logged — a broken handler never fails the capture.

CSP Nonce

Pass the CSP nonce via the cspNonce option:

import html2canvas from 'html2canvas-pro';

html2canvas(element, {
    cspNonce: document.querySelector('meta[name="csp-nonce"]').content
});

Removed: html2canvas.setCspNonce(nonce) has been removed since 2.1.0. Use the cspNonce option passed to html2canvas instead.

Custom isSameOrigin Usage

The customIsSameOrigin option allows you to override the default same-origin detection logic, which is particularly useful in the following scenarios:

1. Handling redirects: When an image URL from your domain redirects to an external domain
2. CDN configurations: When your content is served from multiple domains or CDNs
3. Force CORS mode: When you want to force all images to use CORS regardless of origin

Basic Usage

html2canvas(element, {
    useCORS: true,
    customIsSameOrigin: (src, oldFn) => {
        // If old logic thinks it's not same origin, certainly it's not
        if (!oldFn(src)) {
            return false;
        }
        // Otherwise, we need to check if it's a redirect url
        const targetUrl = new URL(src);
        const pathname = targetUrl.pathname;
        // You can replace it with any logic you want. Including but not limited to: using regular expressions, using asynchronous validation logic
        // Here we simply suppose your biz url starts with /some-redirect-prefix and treat it as a redirect url just for example
        return !pathname.startsWith('/some-redirect-prefix');
    },
    // any other options...
});

Async Validation

The function can also return a Promise for asynchronous validation:

html2canvas(element, {
    useCORS: true,
    customIsSameOrigin: async (src, oldFn) => {
        // You could check against an API that knows which URLs will redirect
        const response = await fetch('/api/check-redirect?url=' + encodeURIComponent(src));
        const data = await response.json();
        return !data.willRedirect;
    },
    // any other options...
});

Force All Images to Use CORS

To force all images to use CORS:

html2canvas(element, {
    useCORS: true,
    customIsSameOrigin: (src, oldFn) => false, // Always report as not same origin
    // any other options...
});

Shadow DOM Support

The iframeContainer option allows you to specify where the temporary iframe should be created. This is particularly useful when rendering elements inside Shadow DOM, as styles defined within the Shadow Root need to be accessible to the cloned content.

Automatic Detection

By default, html2canvas-pro will automatically detect if the target element is inside a Shadow Root and use it as the iframe container:

// Element inside Shadow DOM
const shadowHost = document.querySelector('#my-web-component');
const shadowRoot = shadowHost.shadowRoot;
const elementInShadow = shadowRoot.querySelector('.content');

// Auto-detection: iframe will be created inside the Shadow Root
html2canvas(elementInShadow).then(canvas => {
    document.body.appendChild(canvas);
});

Manual Configuration

You can also explicitly specify the iframe container:

const shadowHost = document.querySelector('#my-web-component');
const shadowRoot = shadowHost.shadowRoot;
const elementInShadow = shadowRoot.querySelector('.content');

html2canvas(elementInShadow, {
    iframeContainer: shadowRoot  // Explicitly use Shadow Root
}).then(canvas => {
    document.body.appendChild(canvas);
});

Use Cases

1. Web Components with Shadow DOM: When capturing custom elements that use Shadow DOM
2. Scoped Styles: When the element has styles defined in <style> tags within the Shadow Root
3. Slot Content: When rendering slotted content that depends on Shadow DOM styles

Complete Example

Here's a complete example using multiple configuration options:

html2canvas(document.getElementById('capture'), {
    scale: 2, // 2x scale for higher resolution
    useCORS: true,
    backgroundColor: '#f5f5f5',
    logging: false,
    imageTimeout: 30000,
    ignoreElements: (element) => {
        return element.classList.contains('do-not-capture');
    },
    onclone: (clonedDoc) => {
        // Modify the cloned document before rendering
        const timestamp = clonedDoc.getElementById('timestamp');
        if (timestamp) {
            timestamp.textContent = new Date().toLocaleString();
        }
    }
}).then(canvas => {
    // Use the resulting canvas
    document.body.appendChild(canvas);
    
    // Or convert to image
    const image = canvas.toDataURL('image/png');
    // Do something with the image...
});

Backward Compatibility

html2canvas-pro keeps existing usage working where possible:

• Element input: In addition to real HTMLElement instances, any object with ownerDocument and ownerDocument.defaultView is accepted (e.g. element-like mocks or cross-realm references). Validation still requires the element to be attached to a document and window.
• Numeric options: Options that expect numbers (scale, width, height, imageTimeout, x, y, windowWidth, windowHeight, scrollX, scrollY) accept string numbers and are coerced before validation.
• Minimal window: If the element’s defaultView does not provide innerWidth, innerHeight, pageXOffset, or pageYOffset, sensible defaults (e.g. 800×600, scroll 0) are used.
• Runtime config: html2canvas.setCspNonce(nonce) and the global setDefaultConfig / getDefaultConfig functions were removed in v2.1.0. Pass cspNonce via the Options object and create a Html2CanvasConfig instance per call instead.
• DOM normalization: The default remains normalizeDom: true (disable animations / reset transforms during capture). Set normalizeDom: false only if you need to preserve the original DOM state.