Guide · Open source
How to use html2canvas: take screenshots of web pages in JavaScript
Updated · written with AI from the project's own documentation and checked against our catalogue data
html2canvas is an open-source JavaScript library, released under the MIT licence, that takes a "screenshot" of a webpage or a section of it directly in the user's browser. It reads the page's DOM and the styles applied to each element, then draws the result onto a canvas element. This guide shows you how to call it, what it needs, and where its output can differ from the real page so you can decide whether it fits your project.
html2canvasniklasvh/html2canvas · ★ 31.9k · MIT Install options & downloads Quick start
- 1Get the library. Install html2canvas with a package manager, or download a ready build from the releases page. Build from source only if you need to.
- 2Load a Promise polyfill if needed. If you target older browsers without Promise support, include a polyfill such as es6-promise before html2canvas.
- 3Pick the element to capture. Choose the DOM element you want as an image. You can pass document.body or any smaller section of the page.
- 4Call html2canvas. Call html2canvas with the element and optional options. It returns a Promise.
- 5Use the resolved canvas. In the then handler, you receive a canvas element. Append it to the page or convert it for download.
- 6Test across browsers. Check the result in each browser you support, since CSS support varies and the output is an approximation.
What html2canvas does and how it works
html2canvas renders the current page as a canvas image by reading the DOM and the styles applied to the elements. The whole image is created on the client's browser, so no server-side rendering is needed.
The README is clear that the result is not a true screenshot. It is rebuilt from information on the page, so it may not be 100% accurate to what a user sees.
Install html2canvas
The source lists package-manager installation as the install method. Ready builds are also available from the project's releases page.
If you want to build from source, you need Node.js and npm. Clone the repository, install dependencies, then build the browser bundle with the commands below.
- Clone the repository (source build only)
- Install dependencies with npm
- Build the browser bundle
git clone git://github.com/niklasvh/html2canvas.git
npm install
npm run buildCheck browser support and the Promise requirement
html2canvas uses Promises and expects them to be available in the global context. Modern browsers support this natively. For older browsers that lack Promise support, include a polyfill such as es6-promise before loading html2canvas.
The README lists these browsers as working with a Promise polyfill: Firefox 3.5+, Google Chrome, Opera 12+, IE9+ and Safari 6+. Because each CSS property has to be built manually, some CSS properties are not yet supported.
- A modern web browser, or a Promise polyfill for older ones
- Node.js and npm only if you build from source
Capture an element with html2canvas
Call html2canvas with the element you want to capture and an optional options object. The function returns a Promise that resolves to a canvas element. Add a handler with then to receive it.
The README example appends the captured canvas to the page. In a real tool you would instead convert the canvas to an image or offer it for download, depending on your needs.
html2canvas(document.body).then(function(canvas) {
document.body.appendChild(canvas);
});Handle cross-origin content
html2canvas does not get around browser content policies. Content loaded from another origin will not render unless it is brought onto the same origin. The README suggests using a proxy for this. The project wiki has a page on proxies with more detail.
Plan for this before you build. If your page depends on third-party images or resources, a proxy setup is part of the work.
Know the limits before you ship
The README describes the script as very experimental. The author does not recommend using it in production yet, and notes that major changes are still expected. Treat it as a good fit for prototypes and non-critical features unless you accept that risk.
The library is heavily dependent on the browser and is not suitable for Node.js. If you need server-side rendering or pixel-perfect captures, the README points away from this library.
- Output may differ from the real page because it is rebuilt, not captured
- Not suitable for Node.js
- Not recommended for production use yet
- Cross-origin content needs a proxy
What people use it for
- Letting users save part of a dashboard or report as an image
- Building an in-browser tool that needs a picture of rendered HTML
- Creating an image on the client so the content never has to be rendered on a server
- Prototyping a share or export feature where approximate rendering is acceptable
Frequently asked questions
Is html2canvas free to use?
html2canvas is released under the MIT licence, as stated in the project's listing. The MIT licence is permissive, but check the licence text itself for your own legal requirements.
How do I install html2canvas?
The listed install method is a package manager. You can also download ready builds from the project's releases page, or clone the repository and run npm install followed by npm run build to build the browser bundle.
Does html2canvas work in Node.js?
No. The README says the library is heavily browser-dependent and not suitable for use in Node.js.
Why does my html2canvas image look different from the page?
The README explains that html2canvas does not take a real screenshot. It rebuilds the image from the DOM and styles, so the output may not be exactly accurate. Some CSS properties are also not yet supported.
Why are images from another domain missing in my capture?
Browser content policies block cross-origin content, and html2canvas does not bypass them. The README recommends a proxy to bring that content onto the same origin.
What are alternatives to html2canvas?
The project lists dom-to-image, html-to-image, rasterizehtml and puppeteer as comparable projects. This guide does not compare their performance or output quality, so test the options against your own pages.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
html2canvas suits front-end developers who need to let users export part of a page as an image on the client, and who can accept approximate rendering. It is a poor choice for pixel-perfect captures, Node.js rendering, or production systems that cannot tolerate an experimental library. Compare it with the listed alternatives before committing.
Install options & downloads