28/2/24, 11:32 canvas-size - Determine the maximum area, height, width, and custom dimensions of an HTML canvas element.

canvas-size
npm v2.0.0 checks passing code quality A coverage 100% License MIT jsDelivr 76k hits/month

Sponsor ❤

Determine the maximum area, height, width, and custom dimensions of an HTML
<canvas> element.

Version 2.x contains new features and breaking changes (see the Changelog
for details). Documentation for version 1.x is available on GitHub.

Why?

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.

Demo

https://jhildenbiddle.github.io/canvas-size/#/?id=test-results 1/16
28/2/24, 11:32 canvas-size - Determine the maximum area, height, width, and custom dimensions of an HTML canvas element.

HTML CSS JS Res

import canvasSize from 'https://cdn.jsdelivr.net/npm/canvas-

size@2/dist/canvas-size.esm.min.js';

const results = await canvasSize.maxArea({

max: 18000,
min: 1,
step: 100,
// useWorker: true,

🔴
onError(results) {
log(' ', results);
},
});

log(results.success ? ' 🟢 ' : ' 🔴

', results);

Features

Determine the maximum <canvas> area, height, and width

Test custom <canvas> dimensions
Web worker + OffscreenCanvas support
UMD and ES6 module available
Lightweight (< 1k min+gzip) and dependency-free

Browser Support

Chrome 24+
Edge 12+
Firefox 26+
Safari 8+
Internet Explorer 10+

Installation

NPM

https://jhildenbiddle.github.io/canvas-size/#/?id=test-results 2/16
28/2/24, 11:32 canvas-size - Determine the maximum area, height, width, and custom dimensions of an HTML canvas element.

bash

npm install canvas-size

js

import canvasSize from 'canvas-size';

CDN

Available on jsdelivr (below), unpkg, and other CDN services that auto-publish npm
packages.

html

<!-- ES Module (latest v2.x.x) -->

<script
type="module"
src="https://cdn.jsdelivr.net/npm/canvas-size@2/dist/canvas-size.esm.mi
></script>

html

<!-- Global "canvasSize" (latest v2.x.x) -->

<script src="https://cdn.jsdelivr.net/npm/canvas-size@2"></script>

Note the @ version lock in the URLs above. This prevents breaking changes
in future releases from affecting your project and is therefore the safest
method of loading dependencies from a CDN. When a new major version is
released, you will need to manually update your CDN URLs by changing the
version after the @ symbol.

Usage

All HTML canvas tests are performed asynchronously. A failed test will return
immediately. Successful test times are dependent upon the canvas dimensions, browser,
and hardware.

https://jhildenbiddle.github.io/canvas-size/#/?id=test-results 3/16
28/2/24, 11:32 canvas-size - Determine the maximum area, height, width, and custom dimensions of an HTML canvas element.

Test results are available using promises and callbacks.

Promises

Each canvasSize() method returns a Promise Object (if supported). The promise
will will resolve after the first successful canvas test or after all tests have been completed
with the following test result data:

js

{
success: boolean, // Status of last test
width: number, // Width of last canvas
height: number, // Height of last canvas
testTime: number, // Time to complete last test
totalTime: number, // Time to complete all tests
}

Test results are provided after the promise has resolved using a then handler:

js

// Use maxArea(), maxHeight(), maxWidth(), or test()

canvasSize
.test({
// ...
})
.then(results => {
console.log(results); // { success: <boolean>, ... }
});

Alternatively, the await operator can be used to simplify handling asynchronous

events. This requires calling canvasSize within an async function or in an environment
that supports top-level await :

js

const results = await canvasSize.test({

// ...
});

https://jhildenbiddle.github.io/canvas-size/#/?id=test-results 4/16
28/2/24, 11:32 canvas-size - Determine the maximum area, height, width, and custom dimensions of an HTML canvas element.

console.log(results); // { success: <boolean>, height: <number>, width: <

Destructuring assignment allows for simplified access to test result values:

js

const { success, width, height } = await canvasSize.test({

// ...
});

if (success) {
console.log(`Created canvas: ${width} x ${height}`);
}

Promises and callbacks can be used together to provide individual test results when
multiple tests are being performed:

js

const { success, width, height } = await canvasSize.maxArea({

// ...
onError({ width, height, testTime, totalTime }) {
console.log('Error', width, height, testTime, totalTime);
},
});

if (success) {
console.log('Success', width, height, testTime, totalTime);
}

// Error <width> <height> <testTime> <totalTime>

// Error <width> <height> <testTime> <totalTime>
// Error <width> <height> <testTime> <totalTime>
// ...
// Success <width> <height> <testTime> <totalTime>

Callbacks

https://jhildenbiddle.github.io/canvas-size/#/?id=test-results 5/16
28/2/24, 11:32 canvas-size - Determine the maximum area, height, width, and custom dimensions of an HTML canvas element.

Callback functions can be used to access canvas test result instead of or in addition to
promises. There are three key differences between using canvasSize promises and
callbacks:

Legacy browsers without Promise Object support must use callbacks.

Promises and the await operator simplify asynchronous event handling.
The onError callback function provides canvas test results for each failed test when
multiple tests are performed using the maxArea() , maxHeight() , maxWidth() ,
or test() methods. A promise only projects a single failed test result after all
canvas tests have completed.

js
// maxArea(), maxHeight(), maxWidth(), or test()
canvasSize.maxArea({
// ...
onError({ width, height, testTime, totalTime }) {
console.log('Error', width, height, testTime, totalTime);
},
onSuccess({ width, height, testTime, totalTime }) {
console.log('Success', width, height, testTime, totalTime);
},
});

// Error <width> <height> <testTime> <totalTime>

// Error <width> <height> <testTime> <totalTime>
// Error <width> <height> <testTime> <totalTime>
// ...
// Success <width> <height> <testTime> <totalTime>

Legacy-compatible ES5 syntax:

js
// maxArea(), maxHeight(), maxWidth(), or test()
canvasSize.maxArea({
// ...
onError: function (results) {
console.log('Error', results);
},
onSuccess: function (results) {
console.log('Success', results);

https://jhildenbiddle.github.io/canvas-size/#/?id=test-results 6/16
28/2/24, 11:32 canvas-size - Determine the maximum area, height, width, and custom dimensions of an HTML canvas element.

},
});

// Error { width: <number>, height: <number>, testTime: <number>, totalTi

// Error { width: <number>, height: <number>, testTime: <number>, totalTi
// Error { width: <number>, height: <number>, testTime: <number>, totalTi
// ...
// Success { width: <number>, height: <number>, testTime: <number>, total

Web Workers

Browsers that support web workers and OffscreenCanvas can have canvas tests
performed on a separate thread by setting useWorker:true . This can prevent the
browser from becoming unresponsive while testing on the browser’s main thread.

Note: Browsers without support for web workers and OffscreenCanvas will ignore this
option and perform tests on the main thread.

js

// maxArea(), maxHeight(), maxWidth(), or test()

canvasSize.maxArea({
// ...
useWorker: true,
});

At the time of this writing, Firefox and Safari are able to perform canvas tests
using a web worker at the same speed or better compared to tests run on the
main thread. Unfortunately, Blink-based browsers like Chrome and Edge
perform significantly slower when using web workers. This is a long-standing
issue and the cause is unknown.

Methods

maxArea
https://jhildenbiddle.github.io/canvas-size/#/?id=test-results 7/16
28/2/24, 11:32 canvas-size - Determine the maximum area, height, width, and custom dimensions of an HTML canvas element.

Determines the maximum area/height/width of an HTML canvas element on the client.

Returns a promise or undefined in legacy browsers.

When options.max is not specified, 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 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 accurate results but will
require more time to complete due the increased number of tests that will run.

Options

max: Maximum canvas height/width to test (area = max * max)

Type: number
Default: See description above
min: Minimum canvas height/width to test (area = min * min)
Type: number
Default: 1
step: Value to subtract from test width/height after each failed test
Type: number
Default: 1024
useWorker: Determines if canvas tests will be performed asynchronously on a
separate browser thread. Requires modern browser with web worker and
OffscreenCanvas support. If web worker and OffscreenCanvas support is not available,
tests will be performed on the main browser thread.
Type: boolean
Default: false
onError: Callback invoked after each unsuccessful test
Type: function
Arguments:
1. width: Width of canvas element (will be 1 for maxHeight() )
2. height: Height of canvas element (will be 1 for maxWidth() )
3. testTime: Time to complete last test in milliseconds

https://jhildenbiddle.github.io/canvas-size/#/?id=test-results 8/16
28/2/24, 11:32 canvas-size - Determine the maximum area, height, width, and custom dimensions of an HTML canvas element.

4. totalTime: Time to complete all test in milliseconds

onSuccess: Callback invoked after each successful test
Type: function
Arguments:
1. width: Width of canvas element (will be 1 for maxHeight() )
2. height: Height of canvas element (will be 1 for maxWidth() )
3. testTime: Test execution time in milliseconds
4. totalTime: Time to complete all test in milliseconds

Examples

The following examples use maxArea() . Usage for maxHeight() and maxWidth()
is identical.

js

// Optimized tests
const { success, width, height } = await canvasSize.maxArea();

js
// Custom tests with web worker
const { success, width, height } = await canvasSize.maxArea({
max: 16384,
min: 1, // default
step: 1024, // default
useWorker: true,
});

Using callbacks instead of promises:

js

// Optimized tests
canvasSize.maxArea({
onSuccess({ width, height, testTime, totalTime }) {
console.log('Success:', width, height, testTime, totalTime);
},
});

// Custom tests with web worker

canvasSize.maxArea({

https://jhildenbiddle.github.io/canvas-size/#/?id=test-results 9/16
28/2/24, 11:32 canvas-size - Determine the maximum area, height, width, and custom dimensions of an HTML canvas element.

max: 16384,
min: 1, // default
step: 1024, // default
useWorker: true,
onSuccess({ width, height, testTime, totalTime }) {
console.log('Success:', width, height, testTime, totalTime);
},
});

maxHeight

Details are identical to maxArea method except for method name:

js

canvasSize.maxHeight;

maxWidth

Details are identical to maxArea method except for method name:

js

canvasSize.maxWidth;

test

Determines if the dimension(s) specified exceed the HTML canvas size limitations of the
browser. Returns a promise or undefined in legacy browsers.

To test a single dimension, use options.width and options.height . To test

multiple dimensions, use options.sizes to provide an array of
[width, height] combinations (see example below).

Options

width: Width of the canvas to test

Type: number

https://jhildenbiddle.github.io/canvas-size/#/?id=test-results 10/16
28/2/24, 11:32 canvas-size - Determine the maximum area, height, width, and custom dimensions of an HTML canvas element.

height: Height of the canvas to test

Type: number
sizes: A two-dimensional array of canvas dimensions to test
Type: array (see examples below)
useWorker: Determines if canvas tests will be performed asynchronously on a
separate browser thread. Requires modern browser with web worker and
OffscreenCanvas support. If web worker and OffscreenCanvas support is not available,
tests will be performed on the main browser thread.
Type: boolean
Default: false
onError: Callback invoked after each unsuccessful test
Type: function
Arguments:
1. width: width of canvas element
2. height: height of canvas element
3. testTime: Time to complete last test in milliseconds
4. totalTime: Time to complete all test in milliseconds
onSuccess: Callback invoked after each successful test
Type: function
Arguments:
1. width: width of canvas element
2. height: height of canvas element
3. testTime: Time to complete last test in milliseconds
4. totalTime: Time to complete all test in milliseconds

Returns

boolean when testing a single dimension. Returns true if the dimensions are
within the browser’s size limitations or false when exceeded.

Examples

js
// Single test
const { success } = await canvasSize.test({
height: 16384,
width: 16384,
});

https://jhildenbiddle.github.io/canvas-size/#/?id=test-results 11/16
28/2/24, 11:32 canvas-size - Determine the maximum area, height, width, and custom dimensions of an HTML canvas element.

js

// Multiple tests with web worker

const { success, width, height } = await canvasSize.test({
sizes: [
[16384, 16384],
[8192, 8192],
[4096, 4096],
useWorker: true,
],
});

Using callbacks:

js

// Single test
canvasSize.test({
height: 16384,
width: 16384,
onError({ width, height, testTime, totalTime }) {
console.log('Error:', width, height, testTime, totalTime);
},
onSuccess({ width, height, testTime, totalTime }) {
console.log('Success:', width, height, testTime, totalTime);
},
});

js

// Multiple tests with web worker

canvasSize.test({
sizes: [
[16384, 16384],
[8192, 8192],
[4096, 4096],
],
useWorker: true,
onError({ width, height, testTime, totalTime }) {
console.log('Error:', width, height, testTime, totalTime);
},
onSuccess({ width, height, testTime, totalTime }) {

https://jhildenbiddle.github.io/canvas-size/#/?id=test-results 12/16
28/2/24, 11:32 canvas-size - Determine the maximum area, height, width, and custom dimensions of an HTML canvas element.

console.log('Success:', width, height, testTime, totalTime);

},
});

Test Results

Some tests were conducted using virtualized devices courtesy of BrowserStack. Results
may vary based on hardware and operating system, most notably on lower-end mobile
devices with less capable hardware.

Desktop

Browser (OS) Max Width Max Height Max Area (Total)

Chrome 73+ (Mac, Win) 65,535 65,535 16,384 x 16,384 (268,435,456)

Chrome < 73 (Mac, Win) 32,767 32,767 16,384 x 16,384 (268,435,456)

Edge 80+ (Mac, Win) 65,535 65,535 16,384 x 16,384 (268,435,456)

Edge 15 - 18 (Win) 16,384 16,384 16,384 x 16,384 (268,435,456)

Firefox 122+ (Mac, Win) 32,767 32,767 23,168 x 23,168 (536,756,224)

Firefox < 122 (Mac, Win) 32,767 32,767 11,180 x 11,180 (124,992,400)

IE 11 (Win) 16,384 16,384 8,192 x 8,192 (67,108,864)

IE 9 - 10 (Win) 8,192 8,192 8,192 x 8,192 (67,108,864)

Safari 5+ (Mac) 4,194,303 8,388,607 16,384 x 16,384 (268,435,456)

Mobile

https://jhildenbiddle.github.io/canvas-size/#/?id=test-results 13/16
28/2/24, 11:32 canvas-size - Determine the maximum area, height, width, and custom dimensions of an HTML canvas element.

Max Max
Browser (OS) Max Area (Total)
Width Height

Chrome 91+ (Android 8 - 16,384 x 16,384

65,535 65,535
11) (268,435,456)

14,188 x 14,188
Chrome 91+ (Android 7) 65,535 65,535
(201,299,344)

16,384 x 16,384
Chrome 91+ (Android 6) 65,535 65,535
(268,435,456)

11,180 x 11,180
Chrome 91+ (Android 5) 65,535 65,535
(124,992,400)

Chrome 68+ (Android 7.1 - 14,188 x 14,188

32,767 32,767
9) (201,299,344)

10,836 x 10,836
Chrome 68+ (Android 6) 32,767 32,767
(117,418,896)

11,402 x 11,402
Chrome 68+ (Android 5) 32,767 32,767
(130,005,604)

IE (Windows Phone 8.x) 4,096 4,096 4,096 x 4,096 (16,777,216)

Mobile Safari 9+ 4,194,303 8,388,607 4,096 x 4,096 (16,777,216)

Known Issues

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.

https://jhildenbiddle.github.io/canvas-size/#/?id=test-results 14/16
28/2/24, 11:32 canvas-size - Determine the maximum area, height, width, and custom dimensions of an HTML canvas element.

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.

Sponsorship

A sponsorship is more than just a way to show appreciation for the open-source authors
and projects we rely on; it can be the spark that ignites the next big idea, the inspiration
to create something new, and the motivation to share so that others may benefit.

If you benefit from this project, please consider lending your support and encouraging
future efforts by becoming a sponsor.

Thank you! 🙏🏻
Contact & Support

Follow 👨🏻‍💻 @jhildenbiddle on Twitter and GitHub for announcements

Create a 💬 GitHub issue for bug reports, feature requests, or questions
Add a ⭐️ star on GitHub and 🐦 tweet to promote the project
Become a 💖 sponsor to support the project and future efforts

License

This project is licensed under the MIT License. See the LICENSE for details.

https://jhildenbiddle.github.io/canvas-size/#/?id=test-results 15/16
28/2/24, 11:32 canvas-size - Determine the maximum area, height, width, and custom dimensions of an HTML canvas element.

Copyright (c) John Hildenbiddle (@jhildenbiddle)

https://jhildenbiddle.github.io/canvas-size/#/?id=test-results 16/16