canvas-size

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

• 🚀 Documentation & Demo
• 🔬 Test Results

Why?

The HTML canvas element is widely supported by modern and legacy browsers, but each browser and platform combination imposes unique size limitations (see Test Results) 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.

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 4+
Edge 12+
Firefox 3.6+
Safari 4+
Internet Explorer 10+

Installation

NPM

npm install canvas-size

import canvasSize from 'canvas-size';

CDN

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

<!-- ES Module (latest v2.x.x) -->
<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/canvas-size@2/dist/canvas-size.esm.min.js"
></script>

<!-- 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 & Options

See the documentation site for details.

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.

Copyright (c) John Hildenbiddle (@jhildenbiddle)

Change Log

2.0.0

2024-02-12

• ❗️ Breaking: All tests are now performed asynchronously
• ❗️ Breaking: Fix recursion error in some browsers when testing a large number of canvas sizes
• ❗️ Breaking: Update promise behavior to always resolve leaving catch for exceptions
• ❗️ Breaking: Update callback functions to receive results object instead of separate arguments
• ❗️ Breaking: Remove usePromise option and return promise automatically if supported
• Add success property to promise results
• Add testTime and totalTime to callback and promise results
• Add new max area limit for Firefox 122+ (23,168 x 23,168)
• Update ES module build from ES5 to ES2015+ syntax
• Update test environment and migrate tests to Playwright
• Update documentation
• Update CI

1.2.6

2023-02-24

• Fix Safari canvas memory usage (#16)

1.2.5

2021-09-04

• Update badges in documentation
• Update browser test results (#14)
• Replace Travis CI with GitHub CI

1.2.4

2021-04-26

• Fix maxArea() test order for more accurate results in Firefox (#12)

1.2.3

2021-03-03

• Fix handling of floating point sizes in Webkit-based browsers (e.g. Safari)

1.2.2

2021-01-28

• Fix reference error after minification (#5, #6)

1.2.1

2020-11-11

• Fix web worker bug in minified esm distributable (#5, #6)

1.2.0

2020-06-18

• Add useWorker option which allows canvas tests to be performed asynchronously on a separate thread (requires Web Worker and OffscreenCanvas support)
• Add "Usage" section to the documentation
• Remove requestAnimationFrame from canvas test loop

1.1.0

2020-05-31

• Add usePromise option which allows the use of standard then(), catch(), and finally() promise methods or async functions in modern browsers (legacy browsers will require a promise polyfill and transpilation to ES5 for async functions)
• Add benchmark return value to onError() and onSuccess() callbacks
• Add new Chrome/Blink height/width limitation to canvas test sizes (#2)
• Add invocation of callbacks when testing a single dimension
• Fix bug that incorrectly set the last item in a generated array of test dimensions to an area test ([dimension, dimension]) instead of a width ([width, 1]) or height ([1, height]) test
• Update method of reading/writing to canvas elements, resulting in a significant performance increase
• Update dependencies

1.0.4

2019-04-08

• Fix memory consumption

1.0.3

2019-01-08

• Update unit test configuration (Karma & Travis)
• Update dependencies

1.0.2

2018-12-23

• Update preferred CDN link to jsdelivr

1.0.0

2018-12-06

• Initial release