html2canvas-pro

https://github.com/yorickshan/html2canvas-pro
Admin
html2canvas-pro is a next generation JavaScript screenshots tool that captures HTML elements and...
Tokens:44,347
Snippets:397
Trust Score:9.4
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### PerformanceMonitor Usage Example

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/api/classes/PerformanceMonitor.html

Demonstrates how to initialize the monitor, wrap a process with start and end calls, and retrieve a summary.

```typescript
const monitor = new PerformanceMonitor(context);monitor.start('clone');await cloneDocument();monitor.end('clone');const summary = monitor.getSummary();
```

--------------------------------

### start(name: string, metadata?: Record<string, any>)

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/api/classes/PerformanceMonitor.html

Starts measuring a performance metric with a unique name.

```APIDOC
## start(name: string, metadata?: Record<string, any>)

### Description
Starts tracking a performance metric.

### Parameters
- **name** (string) - Required - Unique name for this metric.
- **metadata** (Record<string, any>) - Optional - Metadata to attach to the metric.
```

--------------------------------

### Install HTML2Canvas

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/text/text.html

Command to install the html2canvas library using npm.

```bash
npm install --save html2canvas
```

--------------------------------

### Install html2canvas-pro

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/getting-started.md

Use a package manager to add the library to your project.

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

--------------------------------

### Project Build and Test Commands

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/CONTRIBUTING.md

Standard commands for installing dependencies, building the project, running tests, and performing type checks.

```bash
pnpm install
pnpm build       # TypeScript compile + Rolldown bundle
pnpm test        # Run all unit tests (vitest)
pnpm typecheck   # TypeScript type check only
```

--------------------------------

### Basic Box Shadow Examples

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/background/box-shadow.html

Demonstrates various configurations of the box-shadow property, including offset, blur, and spread.

```css
0 0 0 0.5em;
```

```css
0 0 1em;
```

```css
1em 0.5em;
```

```css
1em 0.5em 1em;
```

```css
0 2em 1em -0.7em;
```

```css
0.3em 0.3em lightgreen;
```

```css
0.3em 0.3em 0 0.6em lightgreen;
```

```css
0 2em 0 -0.9em lightgreen;
```

```css
2em 1.5em 0 -0.7em lightgreen;
```

```css
9em 1.2em 0 -0.6em lightgreen;
```

```css
-27.3em 0 lightgreen;
```

```css
0 2em 0 -1em lightgreen;
```

```css
0 0 1em maroon;
```

```css
0 0 1em 0.5em maroon;
```

```css
0 0 1em 1em maroon;
```

```css
-0.4em -0.4em 1em olive;
```

```css
0.4em 0.4em 1em olive;
```

```css
0.4em 0.4em 1em -0.2em olive;
```

```css
0.4em 0.4em 1em 0.4em olive;
```

```css
0 1.5em 0.5em -1em olive;
```

--------------------------------

### Interactive Demo Script

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/getting-started.md

Vue script setup for dynamically loading the library and initializing the demo.

```javascript
import { onMounted } from 'vue'

onMounted(() => {
  // Dynamically load html2canvas-pro
  const script = document.createElement('script')
  script.src = 'https://cdn.jsdelivr.net/npm/html2canvas-pro/dist/html2canvas-pro.min.js'
  script.onload = initDemo
  document.head.appendChild(script)
})

function initDemo() {
  let currentCanvas = null
```

--------------------------------

### Basic Rendering Example

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/README.md

Captures the document body and appends the resulting canvas to the DOM.

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

--------------------------------

### Setup and Styling for Underline Tests

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/text/underline-lineheight.html

Initializes the document body with various font families and text sizes to test underline rendering.

```javascript
function setUp() { document.body.innerHTML = ''; ['arial','verdana','tahoma','courier new'].forEach(function(e) { var div = document.createElement('div'); div.style.fontFamily = e; document.body.appendChild(div); for (var i = 0; i <= 10; i++) { var text = document.createElement('div'); text.textContent = 'Testing texts'; text.style.marginTop = '1px'; text.style.fontSize = (16 + i * 6) + 'px'; div.appendChild(text); } }); }
```

--------------------------------

### Example Mixed-Case Class Names

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/css/class-name-case.html

These are examples of mixed-case class names that should be correctly applied by the CSS.

```html
.card--Highlight
```

```html
.block__Element--Modifier
```

--------------------------------

### CSS Broken Animation Example

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/animation.html

Demonstrates a CSS animation with a different keyframe and paused playback state. This highlights variations in animation setup.

```css
.animated.broken p {
  animation-name: rotate45;
  animation-duration: 1ms;
  animation-play-state: paused;
}
```

--------------------------------

### Inset Box Shadow Examples

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/background/box-shadow.html

Illustrates the use of inset box shadows, which appear inside the element's border.

```css
inset 0.2em 0.4em red, inset -1em -0.7em red;
```

```css
inset 11em 0 red;
```

```css
inset -1em 0 red;
```

```css
inset 13em 0 3em -3em orange,inset -3em 0 3em -3em blue;
```

```css
inset 11em 0 2em orange;
```

```css
inset 0 0.3em red;
```

```css
inset 0 -1.1em red;
```

```css
inset 1em 0 1em -1em blue;
```

```css
inset 0 0 0.5em blue;
```

```css
inset 0 0 2em blue;
```

```css
inset 0 2em 3em -1em green;
```

```css
inset 0 2em 3em -2em green;
```

```css
inset 0 2em 3em -3em green;
```

```css
inset 0 0 1em khaki;
```

```css
inset 0 0 1em khaki, inset 0 0 1em khaki, inset 0 0 1em khaki, inset 0 0 1em khaki;
```

```css
inset 0 0 0.5em 0.5em khaki;
```

```css
inset 0 0 2em 2em khaki;
```

```css
inset 0 0 0.5em 0.5em indigo, 0 0 0.5em 0.5em indigo;
```

```css
inset 0 0 1em black, inset 0 0 1em black, inset 0 0 1em black, inset 0 0 1em black;
```

```css
inset 0 0 0.7em 0.5em black; /* should be very similar to above */
```

```css
inset 0 2em 3em -1.5em green, inset 0 -2em 3em -2em blue;
```

```css
inset 1em 1em 2em -1em blue;
```

```css
inset 1em 1em 2em -1em blue, inset -1em -1em 2em -1em red;
```

```css
inset 0 2em 3em -2em white, inset 0 -2em 3em -2.5em black;
```

```css
inset 1em 1em 1em -1em white, inset -1em -1em 1em -1em black;
```

```css
inset -1em -1em 1em -1em black, inset 1em 1em 1em -1em white;
```

```css
inset -0.3em -0.3em 0.6em rgba(0,0,0,0.5), inset 0.3em 0.3em 0.6em rgba(256,256,256,0.7);
```

```css
inset 0.3em 0.3em 0.6em rgba(256,256,256,0.5), inset -0.3em -0.3em 0.6em rgba(0,0,0,0.5);
```

--------------------------------

### Negative and Full Rotation with CSS

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/rotate/css-rotate-property.html

Shows examples of applying negative rotations and a full 360-degree rotation using the 'rotate' property.

```css
.rotate-negative {
  rotate: -45deg;
}
```

```css
.rotate-360 {
  rotate: 360deg;
}
```

--------------------------------

### Setup test elements with JavaScript

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/text/linethrough.html

Generates multiple div elements with different font families and sizes to test text-decoration rendering.

```javascript
function setUp() { document.body.innerHTML = ''; ['arial','verdana','courier new'].forEach(function(e) { var div = document.createElement('div'); div.style.fontFamily = e; document.body.appendChild(div); for (var i = 0; i <= 5; i++) { var text = document.createElement('div'); text.textContent = 'Testing texts'; text.style.marginTop = '1px'; text.style.border = '1px solid black'; text.style.fontSize = (16 + i * 6) + 'px'; div.appendChild(text); } }); }
```

--------------------------------

### Setup 2D and WebGL Canvas Contexts

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/images/canvas.html

Initializes 2D and WebGL contexts for HTML canvas elements. Use this to prepare canvases for drawing operations.

```javascript
function setUp() {
  var ctx = document.querySelector('#testcanvas').getContext('2d');
  ctx.fillStyle = "rgb(200,0,0)";
  ctx.fillRect (10, 10, 55, 50);
  ctx.fillStyle = "rgba(0, 0, 200, 0.5)";
  ctx.fillRect (30, 30, 55, 50);

  var gl = document.querySelector('#webglcanvas').getContext('webgl', {preserveDrawingBuffer: true});
  if (gl) {
    gl.clearColor(0.0, 1.0, 0.0, 1.0);
    gl.clear(gl.COLOR_BUFFER_BIT);
  }
}
```

--------------------------------

### Setup Function for Underline Tests

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/text/underline.html

Initializes the test environment by creating DOM elements with various font families and text sizes. This function is called before running the tests.

```javascript
function setUp() { var container = document.querySelector('#test'); container.innerHTML = ''; 
['arial','verdana','courier new'].forEach(function(e) { var div = document.createElement('div'); div.style.fontFamily = e; container.appendChild(div); 
for(var i=1;i<=10;i*=2) { var text = document.createElement('div'); text.innerText = 'Testing texts'; text.style.marginTop = '1px'; text.style.fontSize = (16+i*6) + 'px'; div.appendChild(text); } }); }
```

--------------------------------

### CSS for z-index Example

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/zindex/z-index20.html

Defines styles for a container and two absolutely positioned child elements, controlling their layout and stacking order with z-index.

```css
.container {
  width: 375px;
  height: 603px;
  background-color: #999;
  position: relative;
  margin-bottom: 30px;
}

.child1 {
  height: 500px;
  width: 200px;
  background-color: red;
  z-index: 20;
  position: absolute;
  left: 0;
  top: 0;
}

.child2 {
  height: 50px;
  width: 100px;
  background-color: blue;
  z-index: 20;
  position: absolute;
  left: 30px;
  top: 30px;
}
```

--------------------------------

### Basic CSS Rotation Examples

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/rotate/css-rotate-property.html

Demonstrates basic clockwise and counter-clockwise rotation using the 'rotate' property. Apply these classes to elements to see the effect.

```css
.rotate-45 {
  rotate: 45deg;
}
```

```css
.rotate--45 {
  rotate: -45deg;
}
```

```css
.rotate-90 {
  rotate: 90deg;
}
```

```css
.rotate-180 {
  rotate: 180deg;
}
```

--------------------------------

### Picture Setup and Styling

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/acid2.html

Defines styles for the main picture area, including margins, text alignment, font, and color. It also sets up the 'picture' class for positioning and borders.

```css
#top {
  margin: 100em 3em 0;
  padding: 2em 0 0 .5em;
  text-align: left;
  font: 2em/24px sans-serif;
  color: navy;
  white-space: pre;
}
.picture {
  position: relative;
  border: 1em solid transparent;
  margin: 0 0 100em 3em;
}
.picture {
  background: red;
}
```

--------------------------------

### Basic CSS Styling

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/animation.html

Provides basic styling for the page body and paragraph elements. This sets up the visual foundation for the animation examples.

```css
body {
  font-family: Arial;
}
```

```css
p {
  font: 22px/1 Arial, sans-serif;
  position: absolute;
  top: 25%;
  left: 25%;
  width: 50%;
  height: 50%;
  color: #fff;
  background-color: #666;
  line-height: 90px;
  text-align: center;
}
```

--------------------------------

### Layout and Styling for Animation Examples

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/animation.html

Styles container divs for layout and visual appearance. These elements are used to hold and display the animated content.

```css
div {
  float: left;
  clear: left;
  margin-right: 10px;
  background-color: #ccc;
  width: 180px;
  height: 180px;
  position: relative;
}
```

--------------------------------

### HTML Structure for z-index Example

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/zindex/z-index12.html

Basic HTML structure with nested divs to demonstrate z-index behavior. Ensure elements have 'position' set to something other than 'static' for z-index to apply.

```html
<div id="div1">\n  <div id="div2"></div>\n  <div id="div3"></div>\n</div>
```

--------------------------------

### Complex Multi-Layered Radial Gradients (Webkit)

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/background/radial-gradient.html

Demonstrates a complex background using multiple layered radial gradients with transparency. This example is specific to Webkit browsers.

```css
background-image: -webkit-gradient(radial, 45 45, 10, 52 50, 30, from(#A7D30C), to(rgba(1,159,98,0)), color-stop(90%, #019F62)), -webkit-gradient(radial, 105 105, 20, 112 120, 50, from(#ff5f98), to(rgba(255,1,136,0)), color-stop(75%, #ff0188)), -webkit-gradient(radial, 95 15, 15, 102 20, 40, from(#00c9ff), to(rgba(0,201,255,0)), color-stop(80%, #00b5e2)), -webkit-gradient(radial, 0 150, 50, 0 140, 90, from(#f4f201), to(rgba(228, 199,0,0)), color-stop(80%, #e4c700));
```

--------------------------------

### Define a CSS Property Descriptor

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/CONTRIBUTING.md

Example of creating a property descriptor for keyword-only CSS properties using the IDENT_VALUE parsing type.

```typescript
// For keyword-only properties (e.g., display: block | inline | none)
import { IPropertyIdentValueDescriptor, PropertyDescriptorParsingType } from '../property-descriptor';
import { Context } from '../../core/context';

export const enum MY_PROPERTY {
    VALUE_A = 0,
    VALUE_B = 1
}

export const myProperty: IPropertyIdentValueDescriptor<MY_PROPERTY> = {
    name: 'my-property',
    initialValue: 'value-a',
    prefix: false,   // true for -webkit- prefixed properties
    type: PropertyDescriptorParsingType.IDENT_VALUE,
    parse: (_context: Context, value: string) => {
        switch (value) {
            case 'value-b': return MY_PROPERTY.VALUE_B;
            case 'value-a':
            default: return MY_PROPERTY.VALUE_A;
        }
    }
};
```

--------------------------------

### Complex Multi-Layered Radial Gradients (Moz)

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/background/radial-gradient.html

Demonstrates a complex background using multiple layered radial gradients with transparency. This example is specific to Mozilla browsers.

```css
background-image: -moz-radial-gradient(42px 42px, circle farthest-corner, #A7D30C 0%, #A7D30C 3%, rgba(1,159,98,0) 11%), -moz-radial-gradient(45px 45px, circle farthest-corner, #019F62 0%, #019F62 13%, rgba(255,255,255,0) 16%, rgba(255,255,255,0) 100%), -moz-radial-gradient(102px 102px, circle farthest-corner, #ff5f98 0%, #ff5f98 15%, rgba(255,1,136,0) 27%), -moz-radial-gradient(105px 105px, circle farthest-corner, #FF0188 0%, #FF0188 28%, rgba(255,255,255,0) 32%, rgba(255,255,255,0) 100%), -moz-radial-gradient(92px 12px, circle farthest-corner, #00c9ff 0%, #00c9ff 10%, rgba(0,181,226,0) 26%), -moz-radial-gradient(95px 15px, circle farthest-corner, #00b5e2 0%, #00b5e2 28%, rgba(255,255,255,0) 31%, rgba(255,255,255,0) 100%), -moz-radial-gradient(0px 150px, circle farthest-corner, #f4f201 0%, #f4f201 25%, rgba(228,199,0,0) 45%), -moz-radial-gradient(0px 150px, circle farthest-corner, #e4c700 0%, #e4c700 47%, rgba(255,255,255,0) 50%, rgba(255,255,255,0) 100%);
```

--------------------------------

### Apply clip-path shapes to HTML elements

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/features.md

Examples of applying various clip-path shapes to images and div elements using inline CSS styles.

```html
<!-- Circular avatar -->
<img src="avatar.jpg" style="clip-path: circle(50%);" />

<!-- Diamond shape -->
<div style="clip-path: polygon(50% 0%, 100% 50%, 50% 100%, 0% 50%);">
  content
</div>

<!-- Inset frame -->
<div style="clip-path: inset(10%);">
  content
</div>

<!-- Ellipse crop -->
<div style="clip-path: ellipse(60% 40% at 50% 50%);">
  content
</div>

<!-- SVG path (triangle, local coordinates) -->
<div style="width: 200px; height: 200px; clip-path: path('M 100 0 L 200 200 L 0 200 Z');">
  content
</div>
```

--------------------------------

### Another Relative Positioning Example

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/zindex/z-index9.html

Illustrates a second relatively positioned element with a lower z-index (2). This element will be stacked below the previous relative div.

```css
#reldiv2 {
  z-index: 2;
  position: relative;
  height: 100px;
  top: 15px;
  left: 20px;
  border: 1px solid #669966;
  background-color: #ccffcc;
  margin: 0px 50px 0px 50px;
  text-align: center;
}
```

--------------------------------

### Second Absolute Positioning Example

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/zindex/z-index9.html

Displays another absolutely positioned element with a z-index of 1. This element will be at the bottom of the stacking context among positioned elements.

```css
#absdiv2 {
  z-index: 1;
  position: absolute;
  width: 150px;
  height: 350px;
  top: 10px;
  right: 10px;
  border: 1px solid #990000;
  background-color: #ffdddd;
  text-align: center;
}
```

--------------------------------

### Automatic Shadow DOM Detection

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/configuration.md

The library automatically detects Shadow Roots when capturing elements. No additional configuration is required for standard Shadow DOM setups.

```javascript
// 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);
});
```

--------------------------------

### Custom isSameOrigin: Handle redirect images

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/options/custom-is-same-origin.html

This example demonstrates using customIsSameOrigin to specifically handle redirect images. It checks if the source URL includes '/redirect-image' and returns false for it, while using the default check for other sources. This ensures proper CORS handling for redirected resources.

```javascript
const h2cTests = [
  {
    name: 'With customIsSameOrigin for handling redirect',
    options: {
      useCORS: true,
      logging: true,
      customIsSameOrigin: (src, oldFn) => {
        // Mark the redirect-image as not same origin
        if (src.includes('/redirect-image')) {
          return false;
        }
        return oldFn(src);
      }
    }
  }
];
```

--------------------------------

### Test 2: Scale Parent with Center Origin

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/transform/scale-containing-block.html

This example demonstrates `transform: scale(0.75)` with `transform-origin: center center`. The child element's dimensions are calculated relative to the scaled parent, with positioning adjusted by `left` and `top` percentages.

```css
.scale-center {
  background-color: #343;
  transform: scale(0.75);
  transform-origin: center center;
  width: 300px;
  height: 150px;
  margin-top: 40px;
}

.scale-center .child-centered {
  width: 50%; /* 150px of parent */
  height: 60%; /* 90px of parent */
  background-color: #88cc88;
  position: absolute;
  left: 25%;
  top: 20%;
}
```

--------------------------------

### Basic HTML Structure and Styling

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/acid2.html

Sets up the base HTML and CSS for the test, including font, margin, padding, and background properties. It also defines styles for the introduction message.

```css
html {
  font: 12px sans-serif;
  margin: 0;
  padding: 0;
  overflow: hidden;
  background: white;
  color: red;
}
body {
  margin: 0;
  padding: 0;
}
.intro {
  font: 2em sans-serif;
  margin: 3.5em 2em;
  padding: 0.5em;
  border: solid thin;
  background: white;
  color: black;
  position: relative;
  z-index: 2;
}
.intro * {
  font: inherit;
  margin: 0;
  padding: 0;
}
.intro h1 {
  font-size: 1em;
  font-weight: bolder;
  margin: 0;
  padding: 0;
}
.intro :link {
  color: blue;
}
.intro :visited {
  color: purple;
}
```

--------------------------------

### Circle Cover Radial Gradient (Top-Left Position)

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/background/radial-gradient.html

Defines a circle-shaped radial gradient starting from the top-left corner.

```css
.radialGradient11 { background: -moz-radial-gradient(left top, circle cover, #ababab, #0000ff 33%,#991f1f 100%); background: -webkit-radial-gradient(left top, circle cover, #ababab, #0000ff 33%,#991f1f 100%); background: -o-radial-gradient(left top, circle cover, #ababab, #0000ff 33%,#991f1f 100%); background: -ms-radial-gradient(left top, circle cover, #ababab, #0000ff 33%,#991f1f 100%); background: radial-gradient(left top, circle cover, #ababab, #0000ff 33%,#991f1f 100%); }
```

--------------------------------

### Create 8x8 Pixel Art

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/demo/image-smoothing-demo.html

Generates an 8x8 pixel art on a canvas element. This serves as the source for upscaling examples.

```javascript
function createPixelArt() {
  const canvas = document.getElementById('small-pixel-art');
  const ctx = canvas.getContext('2d');
  const colors = ['#ff0000', '#00ff00', '#0000ff', '#ffff00', '#ff00ff', '#00ffff', '#ffffff', '#000000'];
  for (let y = 0; y < 8; y++) {
    for (let x = 0; x < 8; x++) {
      ctx.fillStyle = colors[(x + y) % colors.length];
      ctx.fillRect(x, y, 1, 1);
    }
  }
}
createPixelArt();
```

--------------------------------

### Build System Output Structure

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/CONTRIBUTING.md

Overview of the generated bundles produced by the Rolldown build system.

```text
Rolldown → CJS bundle (dist/html2canvas-pro.cjs)
        → ESM bundle (dist/html2canvas-pro.esm.js)
        → UMD bundle (dist/html2canvas-pro.js)
        → UMD minified bundle (dist/html2canvas-pro.min.js)
        → Test runner bundle (build/testrunner.js)
```

--------------------------------

### PerformanceMonitor Constructor

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/api/classes/PerformanceMonitor.html

Initializes a new instance of the PerformanceMonitor.

```APIDOC
## constructor(context: Context | null, enabled?: boolean)

### Description
Creates a new PerformanceMonitor instance.

### Parameters
- **context** (Context | null) - Required - The rendering context.
- **enabled** (boolean) - Optional - Whether monitoring is enabled (default: true).
```

--------------------------------

### Configure html2canvas-pro with options

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/configuration.md

Demonstrates using various configuration options like scale, CORS, and the onclone callback to modify the document before rendering.

```typescript
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...
});
```

--------------------------------

### CSS Animation Playback Control

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/animation.html

Applies a CSS animation and sets its playback state to paused. Use this to control when animations start or stop.

```css
.animated.working p {
  animation-name: rotate0;
  animation-duration: 1ms, 1ms;
  animation-play-state: paused;
}
```

--------------------------------

### Configure Canvas Dimensions

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/configuration.md

Demonstrates setting width and height properties for the canvas element.

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

--------------------------------

### logSummary()

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/api/classes/PerformanceMonitor.html

Logs the current performance summary to the console.

```APIDOC
## logSummary()

### Description
Logs the performance summary to the console for debugging purposes.
```

--------------------------------

### Ignore Elements with a Predicate Function

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/options/ignore.html

Use the `ignoreElements` option with a function to conditionally exclude elements. This example ignores elements with the class name 'ignored'.

```javascript
h2cOptions = {ignoreElements: function(element) { return element.className === 'ignored'; }};
```

--------------------------------

### Release Command

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/CONTRIBUTING.md

Command to trigger the release process, which includes version bumping, building, and publishing.

```bash
pnpm release <version>  # e.g., pnpm release 2.1.1
```

--------------------------------

### Test Execution Commands

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/CONTRIBUTING.md

Commands for running the test suite, including watch mode and targeting specific files.

```bash
pnpm test             # Run all tests
pnpm test -- --watch  # Watch mode
pnpm test path/to/file # Run specific test file
```

--------------------------------

### Ignoring Elements by Class Name

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/options/ignore-2.html

Use the ignoreElements option with a function to exclude elements based on their class name. This example ignores any element with the class 'ignored'.

```javascript
var h2cOptions = {ignoreElements: function(element) { return element.className === 'ignored'; }};
```

--------------------------------

### Linear Gradient with Multiple Vendor Prefixes

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/background/linear-gradient.html

Demonstrates a linear gradient with color stops and vendor prefixes for Chrome, Safari, Opera, IE, and Mozilla. Uses W3C standard syntax.

```css
.linearGradient3 {
  background: -moz-linear-gradient(left, #ff0000, #ffff00, #00ff00);
  background: -webkit-gradient(linear, left top, right top, color-stop(#ff0000), color-stop(#ffff00), color-stop(#00ff00));
  background: -webkit-linear-gradient(left, #ff0000, #ffff00, #00ff00);
  background: -o-linear-gradient(left, #ff0000, #ffff00, #00ff00);
  background: -ms-linear-gradient(left, #ff0000, #ffff00, #00ff00);
  background: linear-gradient(left, #ff0000, #ffff00, #00ff00);
}
```

--------------------------------

### Configure canvas dimensions with scale

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/faq.md

Demonstrates how the default scale behavior affects internal resolution on high-DPI displays.

```javascript
// On a Retina display (devicePixelRatio = 2):
html2canvas(element, {
    width: 1920,
    height: 1080
});

// Results in:
// - Canvas CSS display size: 1920px × 1080px
// - Canvas internal resolution: 3840px × 2160px
// - Canvas HTML: <canvas width="3840" height="2160" style="width: 1920px; height: 1080px;">
```

--------------------------------

### Import html2canvas-pro

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/getting-started.md

Import the library into your JavaScript or TypeScript file.

```javascript
import html2canvas from 'html2canvas-pro';
```

--------------------------------

### Configure Image Proxy

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/configuration.md

Provide the URL for a proxy server to handle cross-origin image loading.

```javascript
"https://proxy.example.com/"
```

--------------------------------

### getSummary()

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/api/classes/PerformanceMonitor.html

Retrieves the aggregated performance summary.

```APIDOC
## getSummary()

### Description
Returns the aggregated performance data summary.

### Returns
- **PerformanceSummary** - Aggregated performance data.
```

--------------------------------

### Radial Gradient at 0% 0% with Explicit Size

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/background/radial-gradient-explicit-size.html

Defines a radial gradient starting from the top-left corner (0% 0%) with explicit size parameters. This is a test case from Issue #178.

```css
.test1 { background: radial-gradient(0% 0% at 0% 0%, #235CFC 0%, #1EA3FF 100%); }
```

--------------------------------

### Capturing a Scrolled Area with HTML2Canvas

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/options/scroll.html

Use the scrollX and scrollY options to specify the starting point of the captured area within a larger scrollable document or element. This is useful for capturing content that is not immediately visible in the viewport.

```javascript
var h2cOptions = { x: 250, y: 250, width: 200, height: 100, scrollX: 250, scrollY: 250 };
```

--------------------------------

### Interactive Demo Styles

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/getting-started.md

CSS styles used for the interactive demo section.

```css
.demo-container {
  margin-top: 2rem;
}

#demo-section {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  border-radius: 16px;
  padding: 2rem;
  margin: 2rem 0;
  box-shadow: 0 10px 40px rgba(0,0,0,0.1);
}

.demo-controls {
  background: white;
  border-radius: 12px;
  padding: 2rem;
}

.demo-controls h3 {
  margin-top: 0;
  color: #667eea;
}

.capture-area {
  padding: 30px;
  background: linear-gradient(135deg, #f5da55 0%, #ffa726 100%);
  border-radius: 12px;
  margin: 20px 0;
  box-shadow: 0 4px 15px rgba(0,0,0,0.1);
}

.capture-area h4 {
  color: #333;
  font-size: 1.8em;
  margin: 0 0 15px 0;
}

.capture-area p {
  color: #555;
  margin: 10px 0;
}

.feature-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
  gap: 15px;
  margin: 20px 0;
}

.feature-item {
  background: rgba(255, 255, 255, 0.9);
  padding: 15px;
  border-radius: 8px;
  border-left: 4px solid #667eea;
}

.feature-item strong {
  display: block;
  color: #667eea;
  margin-bottom: 5px;
}

.feature-item span {
  font-size: 0.9em;
  color: #666;
}

.tip {
  font-size: 0.9em;
  margin-top: 15px !important;
}

.button-group {
  display: flex;
  gap: 15px;
  flex-wrap: wrap;
  margin: 20px 0;
}

.demo-button {
  padding: 12px 24px;
  font-size: 1em;
  font-weight: 600;
  border: none;
  border-radius: 8px;
  cursor: pointer;
  transition: all 0.3s ease;
  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
}

.demo-button:hover:not(:disabled) {
  transform: translateY(-2px);
  box-shadow: 0 6px 16px rgba(0,0,0,0.2);
}

.demo-button:active:not(:disabled) {
  transform: translateY(0);
}

.demo-button:disabled {
  opacity: 0.6;
  cursor: not-allowed;
}

.demo-button.primary {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
}

.demo-button.success {
  background: linear-gradient(135deg, #4facfe 0%, #00f2fe 100%);
  color: white;
}

#status {
  margin-top: 20px;
}

.status-message {
  padding: 15px;
  border-radius: 8px;
  font-weight: 600;
  margin: 15px 0;
}

.status-message.success {
  background: #c6f6d5;
  color: #22543d;
}

.status-message.error {
  background: #fed7d7;
  color: #742a2a;
}

.status-message.loading {
  background: #bee3f8;
  color: #2c5282;
  display: flex;
  align-items: center;
  gap: 10px;
}

#result {
  margin-top: 20px;
}

#result h4 {
  color: #667eea;
  margin-bottom: 15px;
}

#result canvas {
  max-width: 100%;
  border-radius: 8px;
  box-shadow: 0 4px 15px rgba(0,0,0,0.1);
  margin-top: 15px;
}

.code-example {
  margin: 2rem 0;
}

@media (max-width: 768px) {
  .feature-grid {
    grid-template-columns: 1fr;
  }
  
  .button-group {
    flex-direction: column;
  }
  
  .demo-button {
    width: 100%;
  }
}
```

--------------------------------

### z-index: 1 Behavior

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/zindex/z-index6.html

Demonstrates the stacking order when one element has a z-index of 1, while another has a default or lower z-index.

```html
<body>
  <div class="z0">z-index:0</div>
  <div class="z1">z-index:1</div>
</body>
```

--------------------------------

### Options Interface

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/api/types/Options.html

Configuration object passed to the html2canvas function to control rendering behavior.

```APIDOC
## Options Interface

### Description
The Options object is used to configure the behavior of the html2canvas rendering process. It combines various configuration categories including clone, window, render, and context settings.

### Properties
- **backgroundColor** (string | null) - Background color for the resulting canvas. Use null for transparent.
- **foreignObjectRendering** (boolean) - Use foreignObject rendering (SVG-based) instead of the default Canvas 2D pipeline.
- **removeContainer** (boolean, optional) - Whether to remove the cloned iframe after rendering. Default: true.
- **cspNonce** (string, optional) - CSP nonce for inline style elements.
- **validator** (Validator, optional) - Custom input validator.
- **skipValidation** (boolean, optional) - Skip pre-render validation of element and options.
- **enablePerformanceMonitoring** (boolean, optional) - Enable performance monitoring and log a timing summary.
- **signal** (AbortSignal, optional) - An AbortSignal that can be used to cancel an in-progress render.
- **imageSmoothing** (boolean, optional) - Enable/disable image smoothing (anti-aliasing) globally. Default: true.
- **imageSmoothingQuality** ("low" | "medium" | "high", optional) - Image smoothing quality level when imageSmoothing is enabled.
```

--------------------------------

### Render Tile Maps

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/features.md

Capture tile-based layouts with disabled interpolation for a clean, retro aesthetic.

```javascript
// Capture retro-style tile map without interpolation
const tileMap = document.getElementById('tile-map');
const mapImage = await html2canvas(tileMap, {
    imageSmoothing: false,
    scale: 3,  // 3x for better visibility
    logging: false
});
```

--------------------------------

### Set Render Window Dimensions

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/configuration.md

Define the window width and height to influence media queries during rendering.

```javascript
1920
```

```javascript
1080
```

--------------------------------

### Default z-index Behavior

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/zindex/z-index6.html

Illustrates the default stacking order when no explicit z-index is set on a relatively positioned element.

```html
<body>
  <div class="z0">z-index:0</div>
  <div>default z-index</div>
</body>
```

--------------------------------

### Comparison with transform: rotate()

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/rotate/css-rotate-property.html

Provides a direct comparison between the modern 'rotate' property and the older 'transform: rotate()' syntax for applying rotation.

```css
.transform-rotate {
  transform: rotate(45deg);
}
```

--------------------------------

### Linear Gradient with Percentage Color Stops

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/background/linear-gradient.html

Creates a linear gradient transitioning from white at 0% to black at 100%.

```css
.linearGradient13 { background: linear-gradient(to top left, white 0%, black 100%); }
```

--------------------------------

### Configure Global Image Smoothing Options

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/features.md

Set imageSmoothing and quality parameters globally within the html2canvas configuration object.

```javascript
// Disable smoothing for pixel art
html2canvas(element, {
    imageSmoothing: false,
    scale: 2  // Upscale 2x without blur
});

// High quality smoothing for photos
html2canvas(element, {
    imageSmoothing: true,
    imageSmoothingQuality: 'high'  // 'low' | 'medium' | 'high'
});
```

--------------------------------

### Manual iframeContainer Configuration

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/configuration.md

Explicitly define the iframe container by passing the Shadow Root to the iframeContainer option. This ensures styles within the Shadow Root are correctly applied to the cloned content.

```javascript
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);
});
```

--------------------------------

### Radial Gradient with Pixel and Percentage Explicit Sizes

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/background/radial-gradient-explicit-size.html

Demonstrates a radial gradient using a mix of pixel (50px width) and percentage (100px height) for its explicit size, positioned at 50px 50px.

```css
.test5 { background: radial-gradient(50px 100px at 50px 50px, #235CFC 0%, #1EA3FF 100%); }
```

--------------------------------

### Basic Box Styling with Solid Border and Radius

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/border/radius.html

Defines a base style for boxes with a solid border and a uniform border-radius. This is used as a foundation for further styling.

```css
.box { width: 200px; height: 200px; display: inline-block; margin: 10px; background:#6F428C; border-style: solid; border-radius: 50px; }
```

--------------------------------

### CSS word-break: normal

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/text/word-break.html

Illustrates the default behavior of word wrapping. Use when standard line breaking is desired.

```css
.normal {
  word-break: normal;
}
```

--------------------------------

### Linear Gradient with Angle Units (Radians)

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/background/linear-gradient.html

Illustrates a linear gradient using an angle defined in radians.

```css
.linearGradient16 { background: linear-gradient(-375.5rad, yellow, orange, red 60%, blue); }
```

--------------------------------

### Custom isSameOrigin: Async check for redirect images

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/options/custom-is-same-origin.html

This snippet illustrates an asynchronous customIsSameOrigin check. It introduces a delay using `await sleep(50)` before returning false for redirect images, simulating a more complex, non-blocking origin verification process. This is useful for scenarios where origin checks might involve network requests or other asynchronous operations.

```javascript
const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
const h2cTests = [
  {
    name: 'With async customIsSameOrigin check',
    options: {
      useCORS: true,
      logging: true,
      customIsSameOrigin: async (src, oldFn) => {
        if (src.includes('/redirect-image')) {
          // Wait briefly to simulate async check
          await sleep(50);
          return false;
        }
        return oldFn(src);
      }
    }
  }
];
```

--------------------------------

### Diagonal Linear Gradient (Top Left to Bottom Right)

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/background/linear-gradient.html

Creates a linear gradient from the top left to the bottom right with multiple color stops. Uses standard W3C syntax.

```css
.linearGradient10 {
  background: linear-gradient(to left top, #0000Ff, rgb(255, 0,0) 50px, green 199px, rgba(0, 0, 0, 0.5) 100.0%);
}
```

--------------------------------

### Implement Interactive Screenshot Capture

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/getting-started.md

Handles element selection, canvas generation with custom options, and image download functionality. Requires existing DOM elements with IDs 'capture', 'captureBtn', 'downloadBtn', 'status', and 'result'.

```javascript
  const captureBtn = document.getElementById('captureBtn')
  const downloadBtn = document.getElementById('downloadBtn')
  const statusDiv = document.getElementById('status')
  const resultDiv = document.getElementById('result')

  function showStatus(message, type = 'success') {
    statusDiv.innerHTML = `<div class="status-message ${type}">${message}</div>`
    if (type === 'success') {
      setTimeout(() => {
        statusDiv.innerHTML = ''
      }, 3000)
    }
  }

  function showLoading() {
    statusDiv.innerHTML = '<div class="status-message loading"><span>⏳</span><span>Generating screenshot...</span></div>'
  }

  async function captureElement() {
    try {
      captureBtn.disabled = true
      showLoading()
      resultDiv.innerHTML = ''

      const element = document.getElementById('capture')
      const canvas = await html2canvas(element, {
        backgroundColor: null,
        scale: 2
      })

      currentCanvas = canvas
      resultDiv.innerHTML = '<h4>✅ Screenshot Result:</h4>'
      resultDiv.appendChild(canvas)
      
      downloadBtn.disabled = false
      showStatus('✅ Screenshot successful! You can click "Download Image" button to save.', 'success')
    } catch (error) {
      console.error('Capture failed:', error)
      showStatus('❌ Capture failed: ' + error.message, 'error')
    } finally {
      captureBtn.disabled = false
    }
  }

  function downloadImage() {
    if (!currentCanvas) {
      showStatus('❌ Please capture first', 'error')
      return
    }

    const link = document.createElement('a')
    link.download = `screenshot-${Date.now()}.png`
    link.href = currentCanvas.toDataURL('image/png')
    link.click()
    
    showStatus('✅ Image downloaded!', 'success')
  }

  captureBtn.addEventListener('click', captureElement)
  downloadBtn.addEventListener('click', downloadImage)
}
</script>
```

--------------------------------

### Diagonal Linear Gradient (Bottom Left to Top Right)

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/background/linear-gradient.html

Creates a linear gradient from the bottom left to the top right. Uses standard W3C syntax.

```css
.linearGradient8 {
  background: linear-gradient(to bottom left, #fff 0%, #00263c 100%);
}
```

--------------------------------

### Capture an Element

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/getting-started.md

Render an element to a canvas and append it to the document body.

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

--------------------------------

### CSSStyleSheet API

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/tests/reftests/webcomponents/webcomponents.html

Demonstrates the use of the CSSStyleSheet API to create and replace styles. This is useful for dynamically applying styles to web components.

```javascript
const sheet = new CSSStyleSheet(); sheet.replaceSync('\* { color: red !important; }')
```

--------------------------------

### Enable CORS for Images

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/configuration.md

Toggle whether to attempt loading images using CORS.

```javascript
true
```

--------------------------------

### clear()

Source: https://github.com/yorickshan/html2canvas-pro/blob/main/docs/api/classes/PerformanceMonitor.html

Clears all stored performance metrics.

```APIDOC
## clear()

### Description
Removes all recorded performance metrics.
```
Tokens:
Raw