Next generation JavaScript screenshot tool.

Getting Started · Configuration · Features · FAQ

html2canvas-pro is a fork of niklasvh/html2canvas that includes various fixes and new features. It offers several advantages over the original html2canvas:

Modern CSS support

• Color functions color() (incl. relative colors), lab(), lch(), oklab(), oklch() — other functions resolve through the browser's computed styles
• background-clip: text support
• mix-blend-mode and background-blend-mode support
• object-fit support for <img/>
• CSS clip-path support (inset, rect, xywh, circle, ellipse, polygon, path)
• CSS writing-mode support (horizontal-tb, vertical-rl, vertical-lr)
• mask-image alpha masks with position/size/repeat (see mask support)
• backdrop-filter: blur() for frosted-glass captures (see backdrop-filter support)
• conic-gradient(), repeating-conic-gradient() and repeating-radial-gradient() — complete gradient family
• text-emphasis (CJK emphasis marks), -webkit-box-reflect, image-set(), border-image-outset / border-image-width
• accent-color, outline, -webkit-text-fill-color, isolation
• filter chain compositing for eligible layers — the full standard filter function set rendered on a dedicated surface with correct layer opacity (see filter support notes)
• Faithful box-shadow rendering, including inset shadows, blur scaling, and shadows through transformed ancestors
• image-rendering CSS property plus imageSmoothing / imageSmoothingQuality options for pixel-perfect output
• Border image, counters & quotes, direction, line-height, transform-origin, and more — see the full feature list

Developer experience

• Security validation — Built-in input validation (Validator API, XSS/SSRF protection)
• Performance monitoring — Built-in PerformanceMonitor with per-phase timings
• Error, progress & cancellation hooks — onError for failed resources, onProgress for pipeline milestones (incl. per-batch image preload progress), AbortSignal cancellation
• TypeScript — First-class type definitions included
• Shadow DOM & Web Components — slot assignment, shadow-root cloning, and automatic iframe placement

Performance

• Deferred (batched, parallel) image preloading
• LRU caches for CSS parsing and gradient patterns
• Native canvas filter fast path with verified SVG fallback

Render speed — html2canvas-pro(latest) vs html2canvas 1.4.1, headless Chromium on Apple M4, scale: 1, median of 10 interleaved runs (benchmark script, reproduce with corepack pnpm bench:render):

On element-heavy pages html2canvas-pro is ~1.6× faster, and it is the only one of the two that can render modern-CSS content at all. Absolute times vary by machine — compare ratios, not milliseconds.

If you found this helpful, don't forget to leave a star 🌟.

npm install html2canvas-pro
pnpm add html2canvas-pro
yarn add html2canvas-pro

import html2canvas from 'html2canvas-pro';

To render an element with html2canvas-pro with some (optional) options, simply call html2canvas(element, options);

html2canvas(document.body).then(function(canvas) {
    document.body.appendChild(canvas);
});

A browser bundle is also available (exposes the global window.html2canvas):

<script src="https://cdn.jsdelivr.net/npm/html2canvas-pro/dist/html2canvas-pro.min.js"></script>
<script>
  html2canvas(document.body).then((canvas) => document.body.appendChild(canvas));
</script>

⚠️ Important: By default, the output canvas dimensions are affected by devicePixelRatio.

// If you need exact pixel dimensions (e.g., for a specific file size):
html2canvas(element, {
    width: 1920,
    height: 1080,
    scale: 1  // Set scale to 1 for exact dimensions
}).then(canvas => {
    // Canvas will be exactly 1920×1080 pixels
    const dataURL = canvas.toDataURL('image/png');
});

See the Configuration Guide for more details.

const controller = new AbortController();

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

// Cancel an in-progress capture:
controller.abort();

html2canvas(element, {
    imageSmoothing: false,       // Disable anti-aliasing globally
    scale: 2                     // Upscale without blur
});
// Or per-element via CSS: style="image-rendering: pixelated"

The package exports html2canvas (default), plus the following named exports:

Full type definitions ship with the package — your editor's IntelliSense covers every option. An HTML API reference can be generated locally with corepack pnpm docs:api (TypeDoc).

The full documentation site lives at yorickshan.github.io/html2canvas-pro:

• Getting Started — installation, usage, live demo
• Configuration — every option with defaults and examples
• Features — supported CSS properties and values
• Proxy — cross-origin image handling
• FAQ — canvas size, tainted canvas, browser limits
• Architecture — how the rendering pipeline works

The project uses pnpm (the version is pinned via the packageManager field — Corepack handles it automatically). Unit tests require Node.js 24 (jsdom 30).

corepack pnpm install
corepack pnpm build          # tsc + Rolldown bundles (CJS/ESM/UMD)
corepack pnpm unittest       # Vitest unit tests
corepack pnpm test           # lint + unit tests + browser reftests (Playwright)
corepack pnpm docs:dev       # VitePress dev server
corepack pnpm docs:api       # Generate the TypeDoc API reference

See CONTRIBUTING.md for the full guide, including how to add a new CSS property.

If you'd like to add a feature, feel free to submit a PR.

Interested in becoming a maintainer? Open an issue or reach out to @yorickshan.

MIT