html2canvas-pro

Compared to the original html2canvas, html2canvas-pro provides enhanced support for modern CSS features and improved developer tooling. Key improvements include:

Color Function Support

Supports advanced CSS color functions:

• color() (including relative colors)
• lab()
• lch()
• oklab()
• oklch()

Layout & Rendering Enhancements

• clip-path: Supports inset(), circle(), ellipse(), polygon(), and path().
• object-fit: Full support for the object-fit property on <img> elements.
• writing-mode: Supports horizontal-tb, vertical-rl, and vertical-lr.
• Image Smoothing: Supports the CSS image-rendering property, as well as imageSmoothing and imageSmoothingQuality configuration options.

Developer Experience & Security

• Security: Includes a built-in Validator API to protect against XSS and SSRF.
• Performance: Includes a built-in PerformanceMonitor API for collecting metrics.
• Typing: Provides first-class TypeScript definitions.
• Testing: Uses Vitest for modern, fast testing.

html2canvas-pro follows a five-phase pipeline to transform a live DOM element into a visual <canvas> representation:

1. DOM Cloning: The source DOM is deep-cloned into a hidden <iframe> using DocumentCloner. This ensures getComputedStyle returns resolved values and prevents cross-origin taint. SlotCloner handles Shadow DOM and <slot> assignments.
2. CSS Parsing: Raw CSS is tokenized via a state-machine-based Tokenizer and then parsed into CSSValue[] by the Parser. Properties are processed using specific property-descriptors.
3. Layout: The Bounds class calculates dimensions and positions, while text.ts handles text measurement and line breaking.
4. Stacking Context: The engine builds a StackingContext tree following the CSS Positioned Layout Module Level 3 painting order (e.g., handling z-index, opacity, and transforms).
5. Canvas Rendering: CanvasRenderer.render(element) orchestrates the final pass, drawing backgrounds, borders, and content (images, forms, etc.) onto the canvas.

DOM Clone → CSS Parse → Layout → Stacking Context → Canvas Render

The customIsSameOrigin option allows you to override default logic for handling redirects, CDNs, or forcing CORS mode. It accepts a function: (src: string, oldFn: (src: string) => boolean) => boolean | Promise<boolean>.

Scenarios:

1. Handling redirects: Check if a URL redirects to an external domain.
2. CDN configurations: Allow multiple domains.
3. Force CORS: Always return false to force CORS mode.

// Basic Usage (Synchronous)
html2canvas(element, {
    useCORS: true,
    customIsSameOrigin: (src, oldFn) => {
        if (!oldFn(src)) {
            return false;
        }
        const targetUrl = new URL(src);
        const pathname = targetUrl.pathname;
        return !pathname.startsWith('/some-redirect-prefix');
    },
});

// Async Validation
html2canvas(element, {
    useCORS: true,
    customIsSameOrigin: async (src, oldFn) => {
        const response = await fetch('/api/check-redirect?url=' + encodeURIComponent(src));
        const data = await response.json();
        return !data.willRedirect;
    },
});

// Force All Images to Use CORS
html2canvas(element, {
    useCORS: true,
    customIsSameOrigin: (src, oldFn) => false,
});

To ensure visual fidelity, html2canvas-pro builds a StackingContext tree using parseStackingContexts(element). This tree follows the CSS painting order, ensuring elements with different z-index, opacity, or transform values are rendered in the correct sequence.

Each ElementPaint node in the tree contains an array of IElementEffect objects, which represent visual modifications applied during the render pass:

• TransformEffect: Matrix transforms with origin offsets.
• ClipEffect: Clipping via paths (e.g., overflow or border-radius).
• OpacityEffect: Global alpha multiplication.
• ClipPathEffect: CSS clip-path shapes.
• BlendEffect: mix-blend-mode composite operations.
• FilterEffect: CSS filter functions.

The effects-renderer.ts manages these by using ctx.save() and ctx.restore() pairs to ensure effects are correctly nested and do not bleed into subsequent render operations.

As of v2.1.0, several global configuration methods have been removed in favor of per-call options.

Removed Global Config

• html2canvas.setCspNonce(nonce) is removed.
• setDefaultConfig and getDefaultConfig are removed.

New Configuration Pattern

Instead of setting global state, pass configuration directly via the Options object in your function call. Use a Html2CanvasConfig instance per call to manage settings.

Supported Input and Types

• Element input: Accepts HTMLElement or any object containing ownerDocument and ownerDocument.defaultView (useful for mocks or cross-realm references). The element must be attached to a document and window.
• Numeric options: Options like scale, width, height, imageTimeout, x, y, windowWidth, windowHeight, scrollX, and scrollY accept both numbers and string numbers (which are coerced).
• DOM normalization: normalizeDom defaults to true. This disables animations and resets transforms during capture. Set normalizeDom: false if you must preserve the original DOM state during the capture process.