canvas-size
Advanced tools
Determine the maximum size of an HTML canvas element and test support for custom canvas dimensions.
Determine the maximum size of an HTML canvas element and test support for custom canvas dimensions.
Browser Support
| IE | Edge | Chrome | Firefox | Safari |
|---|---|---|---|---|
| 9+ | 12+ | 4+ | 3.6+ | 4+ |
The HTML canvas element is widely supported by modern and legacy browsers, but each browser and platform combination imposes unique size limitations that will render a canvas unusable when exceeded. Unfortunately, browsers do not provide a way to determine what their limitations are, nor do they provide any kind of feedback after an unusable canvas has been created. This makes working with large canvas elements a challenge, especially for applications that support a variety of browsers and platforms.
This micro-library provides the maximum area, height, and width of an HTML canvas element supported by the browser as well as the ability to test custom canvas dimensions. By collecting this information before a new canvas element is created, applications are able to reliably set canvas dimensions within the size limitations of each browser/platform.
NPM:
npm install canvas-size
Git:
git clone https://github.com/jhildenbiddle/canvas-size.git
CDN (jsdelivr.com shown, also on unpkg.com):
<!-- ES5 (latest v1.x.x) -->
<script src="https://cdn.jsdelivr.net/npm/canvas-size@1"></script>
<!-- ES6 Module (latest v1.x.x) -->
<script type="module">
import canvasSize from 'https://cdn.jsdelivr.net/npm/canvas-size@1/dist/canvas-size.esm.min.js';
// Do stuff...
</script>
Single tests
Single tests return a boolean to indicate if the specified canvas dimensions are supported by the browser. Failed tests will return almost immediately. Successful test times are dependent upon the browser, hardware, and canvas dimensions used.
var isValidCanvas = canvasSize.test({
width : 8192,
height: 8192
});
console.log(isValidCanvas); // true|false
Multiple tests using callbacks
When multiple tests are performed using maxArea(), maxHeight(), maxWidth(), or test() with multiple sizes defined, the onError callback will be invoked for each failed test until the first successful test invokes the onSuccess callback.
canvasSize.maxArea({
onError: function(width, height, benchmark) {
console.log('Error', width, height, benchmark);
},
onSuccess: function(width, height, benchmark) {
console.log('Success', width, height, benchmark);
}
});
// Error 16387 16387 0.001
// Error 16386 16386 0.001
// Error 16385 16385 0.001
// Success 16384 16384 0.250
Multiple tests using Promises
Browsers with ES6 Promise support (native or via polyfill) can set usePromise:true to handle test results using promise.then() and promise.catch() methods instead of using callbacks. Although promises are typically used for asynchronous tasks, canvas tests will still be synchronous when usePromise is true due to testing requirements, performance implications, and browser compatibility. For asynchronous canvas tests, see the next section.
canvasSize.maxArea({
usePromise: true
})
.then(function(result) {
console.log('Success', result);
});
.catch(function(result) {
console.log('Error', result);
});
// Success { width: 16384, height: 16384, benchmark: 0.250 }
// or
// Error { width: 1, height: 1, benchmark: 0.001 }
Asynchronous tests using Web Workers & OffscreenCanvas
Browsers that support web workers and OffscreenCanvas can set useWorker:true to have canvas tests performed asynchronously on a separate thread. This can prevent the browser from becoming unresponsive while testing on the browser's main thread. Browser without support for web workers and OffscreenCanvas will ignore this option and perform tests synchronously as described above.
Unfortunately, at this time browser support for OffscreenCanvas is limited. In addition, canvas tests that fail immediately on the main thread can take significantly more time using the OffscreenCanvas API (most likely a bug during these early days of OffscreenCanvas support). As a result, the useWorker option can improve application performance by reducing the workload on the main browser thread, but doing so will result in longer test times if/when tests fail.
Note that if useWorker is true and the current browser does not support web workers and OffscreenCanvas, tests will be done on the main thread.
canvasSize.maxArea({
useWorker: true,
onError(width, height, benchmark) {
console.log('Error', width, height, benchmark);
},
onSuccess(width, height, benchmark) {
console.log('Success', width, height, benchmark);
}
});
// Error 16387 16387 0.001
// Error 16386 16386 0.001
// Error 16385 16385 0.001
// Success 16384 16384 0.250
The useWorker option can be combined with the usePromise option as well.
canvasSize.maxArea({
usePromise: true,
useWorker: true,
})
.then(function(result) {
console.log('Success', result);
});
.catch(function(result) {
console.log('Error', result);
});
// Success { width: 16384, height: 16384, benchmark: 0.250 }
// or
// Error { width: 1, height: 1, benchmark: 0.001 }
Determines the maximum area/height/width of an HTML canvas element on the client.
When options.max is unspecified, an optimized test will be performed using known maximum area/height/width values from previously tested browsers and platforms (see Test Results for details). This will return the maximum canvas area/height/width for in the shortest amount of time.
When options.max is specified, the value will be used for the initial area/height/width test, then reduced by the options.step value for each subsequent test until a successful test occurs. This is useful for determining the maximum area/height/width of a canvas element for browser/platform combination not listed in the Test Results section. Note that lower options.step values will provide more granular (and therefore potentially more accurate) results, but will require more time to complete due the increased number of tests that will run.
Callbacks are invoked after each test.
Options
numbernumber1number1024resolve() and reject() will be an object containing width, height, and benchmark properties (see onError/onSuccess for value details). Requires ES6 Promise support (native or via polyfill for legacy browsers).
booleanfalsebooleanfalsefunction1 for maxHeight())1 for maxWidth())function1 for maxHeight())1 for maxWidth())Examples
The following examples use maxArea(). Usage for maxHeight() and maxWidth() is identical.
Using callbacks:
// Default (optimized sizes)
canvasSize.maxArea({
onError: function(width, height, benchmark) {
console.log('Error:', width, height, benchmark);
},
onSuccess: function(width, height, benchmark) {
console.log('Success:', width, height, benchmark);
}
});
// Custom sizes
canvasSize.maxArea({
max : 16384,
min : 1, // default
step: 1024, // default
onError: function(width, height, benchmark) {
console.log('Error:', width, height, benchmark);
},
onSuccess: function(width, height, benchmark) {
console.log('Success:', width, height, benchmark);
}
});
Using ES6 Promises & Web Workers:
// Default (optimized sizes)
canvasSize.maxArea({
usePromise: true,
useWorker : true,
})
.then(({ width, height, benchmark }) => {
console.log(`Success: ${width} x ${height} (${benchmark} ms)`);
});
.catch(({ width, height, benchmark }) => {
console.log(`Error: ${width} x ${height} (${benchmark} ms)`);
});
// Custom sizes
canvasSize.maxArea({
max : 16384,
min : 1, // default
step : 1024, // default
usePromise: true,
useWorker : true,
})
.then(({ width, height, benchmark }) => {
console.log(`Success: ${width} x ${height} (${benchmark} ms)`);
});
.catch(({ width, height, benchmark }) => {
console.log(`Error: ${width} x ${height} (${benchmark} ms)`);
});
Determines if the dimension(s) specified exceed the HTML canvas size limitations of the browser.
To test a single dimension, use options.width and options.height. A boolean will be returned to indicate if the dimensions are within the browser's size limitations. To test multiple dimensions, use options.sizes to provide an array of [width, height] combinations to be tested (see example below). Callbacks are invoked after each test.
Options
numbernumberarray (see examples below)resolve() and reject() will be an object containing width, height, and benchmark properties (see onError/onSuccess for value details). Requires ES6 Promise support (native or via polyfill for legacy browsers).
booleanfalsebooleanfalsefunctionfunctionReturns
boolean when testing a single dimension. Returns true if the dimensions are within the browser's size limitations or false when exceeded.Examples
Using return value:
// Single dimension
var isValidCanvasSize = canvasSize.test({
height: 16384,
width : 16384
});
Using callbacks:
// Multiple dimensions
canvasSize.test({
sizes: [
[16384, 16384],
[8192, 8192],
[4096, 4096]
],
onError: function(width, height, benchmark) {
console.log('Error:', width, height);
},
onSuccess: function(width, height, benchmark) {
console.log('Success:', width, height);
}
});
Using ES6 Promises & Web Workers:
// Multiple dimensions
canvasSize.test({
sizes: [
[16384, 16384],
[8192, 8192],
[4096, 4096]
]
usePromise: true,
useWorker : true,
})
.then(({ width, height, benchmark }) => {
console.log(`Success: ${width} x ${height} (${benchmark} ms)`);
});
.catch(({ width, height, benchmark }) => {
console.log(`Error: ${width} x ${height} (${benchmark} ms)`);
});
Tests conducted using BrowserStack virtualized device are denoted with an asterisk (*). Results from these tests may vary from actual hardware.
| Browser (OS) | Max Width | Max Height | Max Area (Total) |
|---|---|---|---|
| Chrome 83 (Mac, Win *) | 65,535 | 65,535 | 16,384 x 16,384 (268,435,456) |
| Chrome 70 (Mac, Win *) | 32,767 | 32,767 | 16,384 x 16,384 (268,435,456) |
| Edge 17 * | 16,384 | 16,384 | 16,384 x 16,384 (268,435,456) |
| Firefox 63 (Mac, Win *) | 32,767 | 32,767 | 11,180 x 11,180 (124,992,400) |
| IE 11 * | 16,384 | 16,384 | 8,192 x 8,192 (67,108,864) |
| IE 9 - 10 * | 8,192 | 8,192 | 8,192 x 8,192 (67,108,864) |
| Safari 7 - 12 | 4,194,303 | 8,388,607 | 16,384 x 16,384 (268,435,456) |
| Browser (OS) | Max Width | Max Height | Max Area (Total) |
|---|---|---|---|
| Chrome 68 (Android 9) * | 32,767 | 32,767 | 14,188 x 14,188 (201,299,344) |
| Chrome 68 (Android 7.1 - 8) * | 32,767 | 32,767 | 14,188 x 14,188 (201,299,344) |
| Chrome 68 (Android 6) | 32,767 | 32,767 | 10,836 x 10,836 (117,418,896) |
| Chrome 68 (Android 5) * | 32,767 | 32,767 | 11,402 x 11,402 (130,005,604) |
| Chrome 68 (Android 4.4) * | 32,767 | 32,767 | 16,384 x 16,384 (268,435,456) |
| IE (Windows Phone 8.x) | 4,096 | 4,096 | 4,096 x 4,096 (16,777,216) |
| Safari (iOS 9 - 12) | 4,194,303 | 8,388,607 | 4,096 x 4,096 (16,777,216) |
Some browsers become unresponsive during tests
This is a result of the single-threaded nature of JavaScript and the time required to read data from large HTML canvas elements on the client. To accommodate for the brief delay that may occur when testing extremely large canvas sizes, consider the following:
Virtual environments may produce inconsistent results
Tests conducted on virtual machines may produce results that differ from actual hardware. This is to be expected, as the virtualized hardware used in these environments can impose its own unique size limitations separate from the browser.
In some virtualized environments (mostly with older browsers), canvas-size may produce inconsistent results or fail all tests when calling maxArea(), maxHeight(), maxWidth(), and test() using options.sizes. This is a result of the virtual GPU failing after a test canvas exceeds the browser's size limitations, causing all subsequent tests to fail even for canvas dimensions that are actually supported by the browser. The easiest and most reliable way to address these issues is to use a GPU-optimized virtual machine. If this isn't possible and your VM only supports software rendering, avoid iterating over canvas dimensions that exceed the browser's size limitations and instead specify dimensions that are known to be supported by the browser.
This project is licensed under the MIT License. See the MIT LICENSE for details.
Copyright (c) John Hildenbiddle (@jhildenbiddle)
1.2.0
2020-06-18
useWorker option which allows canvas tests to be performed asynchronously on a separate thread (requires Web Worker and OffscreenCanvas support)requestAnimationFrame from canvas test loopFAQs
Determine the maximum area, height, width, and custom dimensions of an HTML canvas element.
The npm package canvas-size receives a total of 39,968 weekly downloads. As such, canvas-size popularity was classified as popular.
We found that canvas-size demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.