To capture a CSS background with html2canvas, pass the element that contains it to html2canvas(), make sure the background asset can load under browser origin rules, and verify that the CSS syntax you use is supported by the library. Use backgroundColor to set a solid fallback behind the rendered content—or null for transparency. Neither setting makes an unsupported or inaccessible CSS background-image appear.
One important distinction: html2canvas reconstructs an image from the DOM and styles it can read; it does not photograph the browser’s already-painted pixels. The result may therefore differ from what you see on screen.
What html2canvas captures—and what it does not
html2canvas builds a canvas representation by reading a page’s DOM and styles and drawing the parts it can handle. It is not a native browser screenshot. As the project documentation explains, the result is based on information available in the page and may not exactly match its real browser rendering.
This matters for backgrounds: the library must recognize the relevant CSS and load any image assets it needs. CSS support is selective, not a guarantee that every browser-supported effect will be reproduced. A background that looks correct in the live page can still be missing or different in the canvas.
#1 Best Overall
- USB-C 2-in-1 storage OTG: The Lexar JumpDrive Dual Drive D40E features USB Type-A and Type-C connectors in a slim, portable form factor for easy device compatibility
- Transfer speeds up to 100MB/s: Based on internal testing, performance may vary depending upon the host device, interface, and usage conditions. 1MB=1,000,000 bytes
- Plug and Play: Widely compatible with USB Type-C smartphones, tablets, laptops, Macs, and traditional Type-A devices, no software installation required. The 360° swivel design allows for easy switching between connectors without the hassle of losing a cap
- Durable & Compact: The Lexar D40E USB memory stick features a metal enclosure, withstands temperatures from 0° to 50° C (32°F to 122°F), and is lightweight at 26g with dimensions of 70.4 x 16.9 x 11.7mm
- Security & Warranty: Securely protects files using an advanced security software solution with 256-bit AES encryption. Backed by a Lexar 3-year limited warranty
First identify which problem you have:
- Missing solid backdrop: set the canvas background with
backgroundColor. - Missing CSS background image: check the element’s computed styles, CSS support, image loading, and cross-origin access.
- Need the exact pixels shown by the browser: use a native screenshot mechanism, such as a browser extension screenshot API, rather than treating html2canvas as a pixel-perfect screen capture.
Basic capture: preserve transparency or choose a solid color
Install and load html2canvas according to the version and build used by your project. Then capture the element after it exists in the document:
const element = document.querySelector('#capture');
if (!element) {
throw new Error('Could not find #capture');
}
const canvas = await html2canvas(element, {
backgroundColor: null,
useCORS: true,
});
document.body.appendChild(canvas);This example asks for a transparent canvas background and enables CORS-mode image loading. It does not guarantee that every CSS background is supported or that another host permits the image to be read. To save the result, use a format supported by the browser canvas, for example:
const link = document.createElement('a');
link.download = 'capture.png';
link.href = canvas.toDataURL('image/png');
link.click();Export can fail if the canvas is tainted by an image that was loaded without appropriate cross-origin permission. Fix the asset’s loading path or permissions; do not rely on allowTaint as an export fix. A tainted canvas cannot be read back for export.
When to set backgroundColor
Set backgroundColor to a color such as '#fff' when you need a solid canvas backdrop. Set it to null when transparency is wanted. The option sets the canvas background where the captured DOM does not supply a background; it is not a replacement for an element’s CSS background-image.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Rank #2
- 2 in 1: USB C + USB 3.0, 32GB usb c flash drive has dual ports, usb 3.0 port is applied to all devices which have usb 3.0 interface and usb c port is widely used in all Android smartphones with OTG function
- High Speed USB 3.0: Read speed up to 90 MB/s, Write speed up to 30 MB/s, the speed of USB 3.0 interface is faster than USB 2.0, save time to wait, increases work productivity. Note: Speed will be limited if you use the USB key in the USB 2.0 interface
- Large Compatibility: The USB 3.0 Connector is compatible with USB 3.0 & USB 2.0 backward USB 1.1 devices, such as Laptop, Desktop, Car Audio, Tablet, TV, Speakers, Projector. USB-C port is compatible with all Android Smartphones
- Expand Storage: Good performance in storing, transferring and sharing digital data with families, friends, colleagues, customers. It can expand the capacity of smartphone, you can watch movies or share pictures when you go on vacation with your family
- Note: Make sure your smartphone is equipped with OTG function and need to open OTG function in Settings when you plug memory stick, then you can transfer easily data bewteen different devices
If the element itself has a solid CSS background, inspect its computed style and the cloned document before changing the canvas fallback. Otherwise, a fallback color can make it harder to distinguish a missing element background from a transparent area.
Make a CSS background image load successfully
Start with the actual element being captured. Confirm that it is the element whose background is defined, that its computed background-image contains the expected URL or gradient, and that the relevant styles are present when html2canvas processes the DOM. If the background is on a child, capture a parent that includes that child or capture the child itself.
Same-origin image
An image served from the page’s origin is usually the simplest case for browser access. Confirm the request succeeds and that the URL is the one used by the computed style. A 404, an incorrect relative URL, or capture running before styles and resources are ready can look like a CSS-rendering problem even when the property is supported.
Cross-origin image with CORS permission
For an image hosted on another origin, useCORS: true tells html2canvas to try loading images in CORS mode. It cannot grant permission. The image server must send suitable CORS response headers for the requesting page’s origin; inspect the browser’s Network panel and the image response headers to confirm.
Recommended Free Tools
Rank #3
- USB-C 2-in-1 storage OTG: The Lexar JumpDrive Dual Drive D40E features USB Type-A and Type-C connectors in a slim, portable form factor for easy device compatibility
- Transfer speeds up to 100MB/s: Based on internal testing, performance may vary depending upon the host device, interface, and usage conditions. 1MB=1,000,000 bytes
- Plug and Play: Widely compatible with USB Type-C smartphones, tablets, laptops, Macs, and traditional Type-A devices, no software installation required. The 360° swivel design allows for easy switching between connectors without the hassle of losing a cap
- Durable & Compact: The Lexar D40E USB memory stick features a metal enclosure, withstands temperatures from 0° to 50° C (32°F to 122°F), and is lightweight at 26g with dimensions of 70.4 x 16.9 x 11.7mm
- Security & Warranty: Securely protects files using an advanced security software solution with 256-bit AES encryption. Backed by a Lexar 3-year limited warranty
const canvas = await html2canvas(element, {
useCORS: true,
backgroundColor: '#fff',
});If the remote server does not permit the request, the image may be omitted to avoid tainting the output. Changing the option on the client does not override the server’s policy.
Use a proxy you control when CORS is unavailable
When you cannot change the image host’s CORS configuration, html2canvas documents a proxy option. Configure a proxy you control and set it on the capture call. Treat the proxy as a security boundary: restrict which destinations it can fetch, validate requests, and avoid turning it into an unrestricted public URL-fetching service. Proxy configuration and behavior depend on your deployment; test it with the actual asset URLs.
These approaches solve different hosting situations. Same-origin hosting avoids a cross-origin image request; CORS-enabled hosting lets the browser request an allowed cross-origin image; a controlled proxy provides an intermediary route when direct CORS access is not available.
Check CSS support and capture timing
Every CSS property needs an implementation in html2canvas, so support is not identical to the browser’s CSS engine. If the background uses a complex or newer syntax, compare it with the project’s supported-features information for the version you run. Do not assume a property works merely because the browser displays it.
Rank #4
- 2-in-1 Dual Design: Features both USB-C and USB-A connectors, making it compatible with phones, tablets, MacBooks, PCs, and laptops-no adapter needed
- Wide Compatibility: Works seamlessly with USB A and USB C devices, ensuring reliable file transfers across smartphones, computers, and more
- Ample Storage Options: Available in 16GB/32GB/64GB/128GB providing plenty of space for photos, videos, music, and documents
- Portable & Lightweight: Compact and durable design for travel, school, or daily use-take your files anywhere
- Plug-and-Play Convenience: No software or drivers required; simply insert into USB-C or USB-A ports and start transferring files instantly
When investigating a missing background, reduce the case to one element and one background rule. Temporarily replace the image or effect with a simple solid color or basic image URL. If the simple case works, add the original CSS features back one at a time; this helps separate a property-support issue from an asset-loading issue.
The options include logging, imageTimeout, and an onclone hook. Logging can help identify resource-loading problems. Adjust imageTimeout when the relevant image needs more time, and use onclone for controlled changes to the cloned document used for rendering. For example, the hook can help ensure a capture-specific class or style is applied to the clone rather than changing the visible page. Avoid using timing adjustments as a substitute for a failed request or missing CORS permission.
Prevent clipping and oversized-canvas failures
If an element is cut off, make the capture viewport dimensions correspond to the element’s scroll dimensions when appropriate. html2canvas’s windowWidth and windowHeight options affect the window dimensions used during rendering. A larger capture can expose more content, but it also increases the canvas size and memory required.
Browser canvas limits vary by browser, platform, and available resources. The html2canvas FAQ gives rough guidance figures, not guaranteed specifications: Chrome/Chromium and desktop Safari are described at approximately 32,767 pixels for a maximum dimension, with Chrome/Chromium at approximately 268 million pixels maximum area; Firefox is described at approximately 32,767 pixels and approximately 472 million pixels; iOS Safari is lower and depends on device RAM. Treat these as warning indicators, not safe limits for every device. A capture can be blank or partial when limits are exceeded, sometimes without a clear error.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteBest Value
- USB-C STORAGE ON THE GO: This sleek drive is supported by Samsung NAND flash and is incredibly compact to fit in the palm of your hand; Count on reliable performance and fast transfer speeds while staying compact
- PERFORMANCE WITH SPEED: No need to choose between performance and reliability; Experience a fast, powerful flash drive that transfers 4GB files in just 11 seconds with up to 400MB/s USB 3.2 Gen 1 read speeds and is backward compatible with USB 3.0/2.0
- MODERN MEETS ICONIC: The ultra-sleek USB-C drive looks as good as it performs; Featuring a reversible plug, the Type-C inserts into your devices seamlessly every time; Transfer large files with style and ease
- ALWAYS CONNECTED: USB-C is compatible across devices, including laptops, tablets, phones and cameras, with enough space for 63,730 photos or maximum 12 hours of 4K video; With up to 256GB of storage space, this pocket-sized thumb drive comes in handy wherever you go
- TOUGH & TRUSTED: Files stay secure, no matter the terrain; Samsung's flash memory technology makes the Type-C a trustworthy drive to store your valuable data; It's waterproof, shock-proof, magnet-proof, temperature-proof, and X-ray-proof body, plus it's backed by a 5-year limited warranty
- Capture only the needed element instead of an unnecessarily large page.
- Use the intended viewport dimensions rather than enlarging them without checking layout effects.
- Test the result on the browser and device where it will be used, especially for long pages and mobile Safari.
- If a very large capture fails, split it into smaller sections and compose or process them separately where your application permits.
Troubleshooting missing or incorrect backgrounds
| Symptom | Likely cause | What to check or change |
|---|---|---|
| The output has no solid backdrop | The canvas background is transparent or no fallback color was chosen. | Set backgroundColor to the required color, or keep null if transparency is intentional. |
| The element’s CSS image is missing | Unsupported background syntax, an unavailable URL, or a cross-origin image blocked from use. | Inspect computed styles and the image request; test a simpler supported background; use CORS only when the host permits it. |
| The browser console reports a tainted canvas or export fails | An image was loaded without permission for cross-origin reading. | Serve it same-origin, configure suitable CORS response headers, or use a controlled proxy. Do not expect allowTaint to make export possible. |
| Some images fail intermittently | The capture may run before resources finish loading, or the image may exceed its loading timeout. | Check the Network panel, enable logging, review imageTimeout, and ensure capture begins after the relevant resources are available. |
| The result is clipped | The render window does not cover the element’s scroll dimensions or the layout changes at the chosen viewport. | Review windowWidth and windowHeight against the element dimensions and test the layout at that size. |
| The result is blank or only partly drawn | The requested canvas may exceed a browser or device limit. | Reduce dimensions or split the capture; test on the target browser and device. |
| A CSS effect differs from the live page | html2canvas reconstructs supported DOM and styles rather than capturing the browser’s painted pixels. | Check the supported-features information and create a minimal reproduction. If actual screen pixels are required, use a native screenshot API. |
Or skip the browser setup
If you need a screenshot of a live public page rather than a canvas of DOM changes in your current app, ScreenshotNeo provides a website screenshot API and MCP server. A one-call cURL request returns an image; consult the ScreenshotNeo API documentation for available formats and options.
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://stripe.com
-o shot.webpUnlike html2canvas, this captures a website URL through a screenshot service; it is not a way to render unsaved DOM state or local-only changes. ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture, and each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; the response includes X-Page-Verdict and X-Billed headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free 1,000 screenshots a month, with no card required.
Performance, reliability, and cost considerations
For html2canvas, larger DOM regions, more background images, and larger output dimensions increase the work required in the browser. A long page can also require a very large canvas, with the browser-limit risks described above. Keep captures scoped to the content needed, wait for the specific resources that matter, and test representative pages on target devices rather than assuming a desktop result will transfer to mobile.
For cross-origin assets, reliability depends on the image host’s response and the browser’s origin rules. A proxy adds an infrastructure dependency and should be secured against arbitrary outbound fetches. For a live-page screenshot service, costs and service behavior depend on the selected plan and response verdict; ScreenshotNeo’s billing behavior and current plan details are described on its site. Do not compare html2canvas and URL screenshot services as if they capture the same input: html2canvas can render a live application element, while a URL service captures a webpage it can access.
Frequently asked questions
Can html2canvas capture a background set with a CSS gradient?
It depends on whether the specific background syntax is implemented by the version you use. Check the project’s supported-features information and test the exact rule; general browser support does not guarantee html2canvas support.
Does setting backgroundColor: null remove the element’s CSS background?
No. It requests a transparent canvas background. The element’s own background is a separate DOM style that html2canvas must be able to read and render.
Can I use html2canvas for a browser extension’s screenshot feature?
It is not the right tool when the requirement is a native screenshot of the browser’s rendered screen. The project FAQ points extension developers toward native browser screenshot APIs for that use case.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
