bubkoo/html-to-image

On GitHub, bubkoo/html-to-image has picked up 7.3k stars, Image Tools, TypeScript. ✂️ Generates an image from a DOM node using HTML5 canvas and SVG.
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
Snapshot
Top contributors
Show top contributors
html-to-image
✂️ Generates an image from a DOM node using HTML5 canvas and SVG.
Fork from dom-to-image with more maintainable code and some new features.
Install
npm install --save html-to-image
Usage
/* ES6 */
import * as htmlToImage from 'html-to-image';
import { toPng, toJpeg, toBlob, toPixelData, toSvg } from 'html-to-image';
/* ES5 */
var htmlToImage = require('html-to-image');
All the top level functions accept a DOM node and rendering options, and return a promise with the requested output:
- toPng
- toSvg
- toJpeg
- toBlob
- toCanvas
- toPixelData
Reuse and customization (v2 branch)
The existing functions remain the shortest path for one image. Create a renderer when several captures share defaults, and create a capture when the same DOM snapshot needs several formats:
import { createRenderer } from 'html-to-image'
const renderer = createRenderer({ pixelRatio: 2, skipFonts: false })
const capture = await renderer.capture(document.querySelector('#receipt')!)
try {
const png = await capture.toPng()
const jpeg = await capture.toJpeg({ quality: 0.85 })
const blob = await capture.toBlob({ type: 'image/webp', quality: 0.8 })
// All three outputs use the same frozen DOM snapshot and rasterization.
} finally {
capture.dispose()
renderer.dispose()
}
For a one-off change, onClone edits the detached copy before resource
discovery. For reusable behavior, register a named plugin. A resource resolver
returns a Blob to handle a URL, or undefined to continue to the next
resolver and then normal fetch:
const renderer = createRenderer({
onClone: ({ root }) => {
root.querySelectorAll('[data-private]').forEach((node) => node.remove())
},
plugins: [{
name: 'app-assets',
resolveResource: async ({ url, kind }, { signal }) => {
if (!url.startsWith('app:')) return undefined
return fetch(`/assets/${url.slice(4)}`, { signal }).then((res) => res.blob())
},
}],
})
For a change tied to each source element, use onCloneNode(original, copy).
It runs synchronously after that element's children, computed styles, pseudo
elements and form state have been copied. Children run before parents. For the
captured source tree, it runs before onClone, plugins, and resource embedding, so edit copy, not
original. Filtered nodes and text nodes do not call it. A thrown error rejects
the capture.
SVG references are resolved after onClone and plugin transforms. Added or
changed references are embedded; removed references are not requested by the
library. Local SVG definitions outside the captured tree are imported during
resource discovery and call onCloneNode at that point. Already copied source
nodes are reused without calling the callback again.
const png = await htmlToImage.toPng(node, {
onCloneNode(original, copy) {
if (original.matches('[data-private]')) copy.textContent = 'Hidden'
},
})
The copy belongs to a private document without a browsing window
(copy.ownerDocument.defaultView === null). Create added nodes through
copy.ownerDocument; read layout and computed styles from original.
The private document prevents WebKit from making native image requests while
styles and image attributes are copied. Relative image addresses are resolved
before embedding, including images added by clone callbacks.
To add CSS to the snapshot, append a style element in onClone:
onClone({ root }) {
const style = root.ownerDocument.createElement('style')
style.textContent = '.export-badge::before { background-image: url("/badge.png") }'
root.append(style)
}
URL values directly declared in background and mask properties are embedded
from inline styles and style rules, including generated ::before/::after
rules and nested groups. They use the capture's resource resolver and cache.
Other CSS URL properties and imported stylesheets are not expanded by this step;
font faces retain the existing font-embedding policy. Custom selectors and media
conditions run in the serialized SVG and do not replace copied computed styles.
stylePropertiesForNode(source) chooses computed CSS properties before they
are copied. Its array applies to that element and its pseudo elements; []
copies none, and undefined copies the full computed style even when a global
includeStyleProperties list exists. Inline styles already on the DOM clone
remain. Include content if a selected pseudo element needs its generated
text. The callback runs synchronously and must return an array or undefined.
Accessible iframe documents keep their own CSS font faces when captured as an
iframe or inside a larger subtree. Relative font URLs use the owning document's
base URL, and document-local family names remain separate in the exported copy.
Font faces introduced by clone transforms are collected too; source styles stay
unchanged. Local-only src: local(...) faces retain their local lookup.
getFontEmbedCSS() includes reachable iframe fonts. When its result contains
iframe fonts, reuse it for the same capture subtree and live iframe documents;
collect it again after frame navigation or replacement. Explicit custom
fontEmbedCSS with ordinary family names continues to apply those names globally.
Each capture has its own cancellation signal and resource cache. capture.dispose()
releases the snapshot; renderer.dispose() cancels outstanding work and releases
its captures. Per-call signal and timeout are supported. exclude accepts
CSS selectors for subtrees. See v2 architecture for
extension order, migration details, and current limits.
Returned canvases belong to the document where the library runs, including when capturing content from an iframe. A completed snapshot can render after its source iframe is removed; it does not need that source document for canvas creation.
The library keeps resource promises only within each capture; a later capture
fetches again subject to the browser's HTTP cache. To request revalidation,
use fetchRequestInit: { cache: 'no-cache' }. Disposal releases library-owned
references; it does not clear the browser's HTTP cache or force garbage collection.
For different credentials by URL, let a resolver handle selected resources and
return undefined for the normal fetch policy:
const renderer = createRenderer({
fetchRequestInit: { credentials: 'include' },
resources: {
resolve: async ({ url }, { signal }) => {
if (new URL(url).origin !== 'https://public-assets.example.com') {
return undefined
}
const response = await fetch(url, { credentials: 'omit', signal })
if (!response.ok) throw new Error(`Asset request failed: ${response.status}`)
return response.blob()
},
},
})
Resolvers own their fetch options, status checks and cancellation. Global
fetchRequestInit applies to the normal fetch path. Servers must permit the
chosen CORS and credential policy; include is not a general Safari fix.
Cloning large trees yields to browser tasks after roughly 16 ms of work so the
page can respond during capture. Set cloneTimeSliceMs to another non-negative
number to adjust this interval, or 0 to disable yielding. Keep the source
DOM stable until capture finishes if other page tasks can modify it.
On WebKit, a large embedded image can be blank on the first rasterization. If affected, opt into repeated rasterization of the same snapshot:
const png = await htmlToImage.toPng(node, { stabilizationAttempts: 3 });
This adds rendering time and is capped at 10 attempts. The default is one.
Go with the following examples.
toPng
Get a PNG image base64-encoded data URL and display it right away:
const node = document.getElementById('my-node');
htmlToImage
.toPng(node)
.then((dataUrl) => {
const img = new Image();
img.src = dataUrl;
document.body.appendChild(img);
})
.catch((err) => {
console.error('oops, something went wrong!', err);
});
Get a PNG image base64-encoded data URL and download it (using download):
htmlToImage
.toPng(document.getElementById('my-node'))
.then((dataUrl) => download(dataUrl, 'my-node.png'));
toSvg
Get an SVG data URL, but filter out all the <i> elements:
function filter (node) {
return (node.tagName !== 'i');
}
htmlToImage
.toSvg(document.getElementById('my-node'), { filter: filter })
.then(function (dataUrl) {
/* do something */
});
toJpeg
Save and download a compressed JPEG image:
htmlToImage
.toJpeg(document.getElementById('my-node'), { quality: 0.95 })
.then(function (dataUrl) {
var link = document.createElement('a');
link.download = 'my-image-name.jpeg';
link.href = dataUrl;
link.click();
});
toBlob
Get a PNG image blob and download it (using FileSaver):
htmlToImage
.toBlob(document.getElementById('my-node'))
.then(function (blob) {
if (!blob) throw new Error('PNG encoding returned no Blob');
if (window.saveAs) {
window.saveAs(blob, 'my-node.png');
} else {
FileSaver.saveAs(blob, 'my-node.png');
}
});
To preview the PNG in a new tab, create a link the user can click:
async function createPreviewLink(node, container) {
const blob = await htmlToImage.toBlob(node);
if (!blob) throw new Error('PNG encoding returned no Blob');
const url = URL.createObjectURL(blob);
const link = document.createElement('a');
link.href = url;
link.target = '_blank';
link.rel = 'noopener';
link.textContent = 'Open PNG preview';
container.appendChild(link);
return () => {
link.remove();
URL.revokeObjectURL(url);
};
}
const discardPreview = await createPreviewLink(
document.getElementById('my-node'),
document.getElementById('preview-links'),
);
// Call discardPreview() when the link and its opened preview are no longer needed.
Keep the object URL alive while the link or opened preview is in use. The returned cleanup function removes the link and releases the URL; it does not close a preview tab. See the File API lifetime rules.
toCanvas
Get a HTMLCanvasElement, and display it right away:
htmlToImage
.toCanvas(document.getElementById('my-node'))
.then(function (canvas) {
document.body.appendChild(canvas);
});
toPixelData
Get the raw RGBA pixel data. toPixelData returns a Uint8ClampedArray;
toImageData also provides the actual output width and height, which account
for pixelRatio and canvas scaling:
const { width, height, data } = await htmlToImage.toImageData(node);
for (let y = 0; y < height; y++) {
for (let x = 0; x < width; x++) {
const offset = 4 * (y * width + x);
const rgba = data.slice(offset, offset + 4);
}
}
React
import React, { useCallback, useRef } from 'react';
import { toPng } from 'html-to-image';
const App: React.FC = () => {
const ref = useRef<HTMLDivElement>(null)
const onButtonClick = useCallback(() => {
if (ref.current === null) {
return
}
toPng(ref.current, { cacheBust: true, })
.then((dataUrl) => {
const link = document.createElement('a')
link.download = 'my-image-name.png'
link.href = dataUrl
link.click()
})
.catch((err) => {
console.log(err)
})
}, [ref])
return (
<>
<div ref={ref}>
{/* DOM nodes you want to convert to PNG */}
</div>
<button onClick={onButtonClick}>Click me</button>
</>
)
}
Options
filter
(domNode: HTMLElement) => boolean
A function taking DOM node as argument. Should return true if passed node should be included in the output. Excluding node means excluding it's children as well.
You can add filter to every image function. For example,
const filter = (node: HTMLElement) => {
const exclusionClasses = ['remove-me', 'secret-div'];
return !exclusionClasses.some((classname) => node.classList?.contains(classname));
}
htmlToImage.toJpeg(node, { quality: 0.95, filter: filter});
or
htmlToImage.toPng(node, {filter:filter})
Not called on the root node.
backgroundColor
A string value for the background color, any valid CSS color value.
width, height
Width and height in pixels to be applied to node before rendering.
Omit a dimension to measure it from the source node. Explicit 0 is preserved
in SVG output; raster output rejects zero-sized captures. Negative or non-finite
dimensions reject capture creation.
canvasWidth, canvasHeight
Scale the captured image to this canvas size in CSS pixels. The pixel buffer's
width and height are multiplied by pixelRatio (and may be reduced by automatic
canvas size limiting).
style
An object whose properties to be copied to node's style before rendering. You might want to check this reference for JavaScript names of CSS properties.
Computed font sizes, including fractional pixels, are preserved on the copy. Capture does not automatically round down or shrink text. Font kerning follows the source element's computed value.
quality
A number between 0 and 1 indicating image quality (e.g. 0.92 => 92%) of the JPEG image.
Defaults to 1.0 (100%)
cacheBust
Set to true to append the current time as a query string to URL requests to enable cache busting.
Defaults to false
includeQueryParams
Full URLs, including query parameters, identify resources by default. Set
false only to opt into the legacy behavior that treats query variants as the
same resource within one capture.
imagePlaceholder
A data URL for a placeholder image that will be used when fetching an image fails.
Defaults to an empty string and will render empty areas for failed images.
onImageErrorHandler
Handle an image load or decode failure. The callback runs with the failed
detached image as this; changes to that copy leave the source unchanged.
Capture waits for a returned Promise before serializing the snapshot. A thrown
error or rejected Promise rejects capture. Without a handler, image errors
reject capture. Custom resource resolver errors also reject capture.
pixelRatio
The pixel ratio of the captured image. Default use the actual pixel ratio of the device. Set 1 to
use as initial-scale 1 for the image.
stabilizationAttempts
Rasterize the frozen SVG this many times and use the last result. This can
help when Safari/WebKit produces a blank embedded image on an initial draw.
Set an integer from 1 to 10; the default is 1. It does not re-read the
source DOM. Each extra attempt uses a fresh SVG image decode context so the
browser cannot keep reusing the first incomplete decode. The frozen SVG
returned by capture.toSvg() stays unchanged. Extra attempts cost time and
remain subject to timeout; they do not guarantee complete rendering.
cloneTimeSliceMs
Maximum uninterrupted clone time in milliseconds. The default is 16;
0 disables yielding. Smaller values improve page responsiveness but may
increase total capture time. This applies to DOM cloning, not SVG serialization
or rasterization.
preferredFontFormat
The format required for font embedding. This is a useful optimisation when a webfont provider specifies several different formats for fonts in the CSS, for example:
@font-face {
name: 'proxima-nova';
src: url("...") format("woff2"), url("...") format("woff"), url("...") format("opentype");
}
Instead of embedding each format, all formats other than the one specified will be discarded. If this option is not specified then all formats will be downloaded and embedded.
fontEmbedCSS
When supplied, the library will skip the process of parsing and embedding webfont URLs in CSS,
instead using this value. This is useful when combined with getFontEmbedCSS() to only perform the
embedding process a single time across multiple calls to library functions.
const fontEmbedCSS = await htmlToImage.getFontEmbedCSS(element1);
html2Image.toSVG(element1, { fontEmbedCSS });
html2Image.toSVG(element2, { fontEmbedCSS });
skipAutoScale
When supplied, the library will skip the process of scaling extra large doms into the canvas object.
You may experience loss of parts of the image if set to true and you are exporting a very large image.
Defaults to false
type
A string indicating the image format. The default type is image/png; that type is also used if the given type isn't supported.
When supplied, toBlob returns a blob matching the given image type and quality.
Defaults to image/png
includeStyleProperties
An array of style property names. Can be used to manually specify which style properties are included when cloning nodes. This can be useful for performance-critical scenarios.
stylePropertiesForNode
A synchronous callback that selects computed style property names for each source element and its pseudo elements. Returning [] copies no computed properties; returning undefined copies all of them, overriding includeStyleProperties for that element. Existing inline styles on the copy remain.
Browsers
Only standard lib is currently used, but make sure your browser supports:
- Promise
- SVG
<foreignObject>tag
The V2 branch runs source and built-package browser tests in Chromium, Firefox, and Playwright WebKit on every pull request. Playwright WebKit is not a real iPhone/iPad Safari device. See the test architecture and release readiness for the exact validation scope. Large DOM performance varies by browser and fixture; the measured V2 comparison is recorded here.
Internet Explorer is not (and will not be) supported, as it does not support SVG <foreignObject> tag.
How it works
There might some day exist (or maybe already exists?) a simple and standard way of exporting parts of the HTML to image (and then this script can only serve as an evidence of all the hoops I had to jump through in order to get such obvious thing done) but I haven't found one so far.
This library uses a feature of SVG that allows having arbitrary HTML content inside of the <foreignObject> tag. So, in order to render that DOM node for you, following steps are taken:
- Clone the original DOM node recursively
- Compute the style for the node and each sub-node and copy it to corresponding clone
- and don't forget to recreate pseudo-elements, as they are not cloned in any way, of course
- Embed web fonts
- find all the
@font-facedeclarations that might represent web fonts - parse file URLs, download corresponding files
- base64-encode and inline content as dataURLs
- concatenate all the processed CSS rules and put them into one
<style>element, then attach it to the clone
- find all the
- Embed images
- embed image URLs in
<img>elements - inline images used in
backgroundCSS property, in a fashion similar to fonts
- embed image URLs in
- Serialize the cloned node to XML
- Wrap XML into the
<foreignObject>tag, then into the SVG, then make it a data URL - Optionally, to get PNG content or raw pixel data as a Uint8Array, create an Image element with the SVG as a source, and render it on an off-screen canvas, that you have also created, then read the content from the canvas
- Done!
Things to watch out for
- If the DOM node you want to render includes a
<canvas>element with something drawn on it, it should be handled fine, unless the canvas is tainted - in this case rendering will rather not succeed. - Rendering will failed on huge DOM due to the dataURI limit varies.
Contributing
Please let us know how can we help. Do check out issues for bug reports or suggestions first.
To become a contributor, please follow our contributing guide.
License
The scripts and documentation in this project are released under the MIT License
Related repositories
three.js (mrdoob/three.js) is an open-source JavaScript library for real-time 3D graphics in the browser, released under the MIT license. It renders through built-in WebGL and WebGPU renderers, with SVG and CSS3D renderers shipped as separate addons. It's the library behind the scene-graph API shown in its own README example: a camera, a geometry, a material, and a mesh composed into a scene and redrawn each frame through an animation loop.
Sharp is a Node-API module that wraps libvips, making it the practical choice when you need to process images in a Node.js environment without the overhead of a full ImageMagick installation. The README claims 4x-5x faster resizing compared to ImageMagick and GraphicsMagick, and it handles the tricky parts correctly: ICC colour profiles, alpha transparency, and auto-orientation all work without surprises. Beyond simple resizing, it covers rotation, extraction, compositing, and gamma correction — useful for building image pipelines that would otherwise require multiple tools stitched together. One concrete upside for local development: most macOS, Windows, and Linux machines need no extra system libraries to run it.
Chart.js is an open-source JavaScript library at chartjs/Chart.js for drawing charts onto an HTML5 canvas element, the output format its own GitHub description names directly. The project has stars and forks on GitHub, ships under the MIT license, and organizes its documentation into getting-started, data-structure, configuration, chart-type, and axes sections rather than one long page.
Apache ECharts is an open-source charting and data visualization library maintained at apache/echarts, written in pure JavaScript and rendered through zrender, a canvas library built for the project. The GitHub repo is available under the Apache-2.0 license, and the README documents an npm package, a CDN build, and extension packages including ECharts GL for 3D and WebGL.
Quick answers
Does bubkoo/html-to-image have a project website?
No homepage URL was recorded for bubkoo/html-to-image in TopGit's last sync. The README tab above frequently contains screenshots and demo links, or check the repository description on GitHub.
Is bubkoo/html-to-image open source?
Yes — bubkoo/html-to-image ships under the MIT license, which makes its source code freely readable (and, depending on license terms, forkable and reusable). Source: github.com/bubkoo/html-to-image.
What else is in the Image Tools space?
bubkoo/html-to-image is tracked by TopGit under the Image Tools category, alongside 8 GitHub-tagged topics. Trending and Topics pages list peer repositories of comparable stars and language.
What is bubkoo/html-to-image?
bubkoo/html-to-image (bubkoo/html-to-image) is a TypeScript project on GitHub. From the project's own README: ✂️ Generates an image from a DOM node using HTML5 canvas and SVG.
What license does bubkoo/html-to-image use?
bubkoo/html-to-image is released under the MIT license. Always verify the LICENSE file directly on GitHub for the authoritative terms — license strings can be edited out of sync with a project's actual stance.
Where do I read more about bubkoo/html-to-image?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/bubkoo/html-to-image is the definitive source.
Why is bubkoo/html-to-image categorized under Image Tools?
TopGit places bubkoo/html-to-image in the Image Tools category based on its GitHub topics and description (tagged: "canvas", "dataurl", "dom"). Categories are assigned from real repository metadata, not editorial guesswork.
Read full README in the tab above.
Curious whether html-to-image is right for you?
Let ChatGPT, Claude, or Perplexity look into it — click below and see what AI actually says about html-to-image.