How to Capture Google Maps with html2canvas in Chrome and Safari
Capture a Google Map with html2canvas, handle tile readiness and CORS, avoid blank exports, and understand Chrome and Safari limits.

Short answer: html2canvas can run in Chrome and Safari, but it does not take a native screenshot of Google Maps. It rebuilds a canvas from DOM elements and styles. Map tiles are usually loaded from another origin, so the browser may skip them or make the canvas unreadable unless the tile response permits CORS. Wait until the map is ready, capture the smallest useful element, request CORS with useCORS: true when the server supports it, and treat browser canvas limits separately from tile-loading and permission problems.
html2canvas’s documentation lists Chrome/Chromium and Safari as supported browsers, while also warning that unsupported or incomplete CSS can produce output that differs from the page. It cannot bypass browser content-policy restrictions. See the html2canvas documentation and its FAQ.
1. Minimal working example
This example captures a map container after a short delay. The delay is only a readiness fallback; it does not solve CORS.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Map capture</title>
<script src="https://cdn.jsdelivr.net/npm/html2canvas@1.4.1/dist/html2canvas.min.js"></script>
<style>
#map { width: 900px; height: 600px; }
</style>
</head>
<body>
<div id="map"><!-- initialize your Google Map here --></div>
<button id="save">Save map</button>
<script>
document.querySelector('#save').addEventListener('click', async () => {
const map = document.querySelector('#map');
const canvas = await html2canvas(map, {
useCORS: true,
allowTaint: false,
backgroundColor: '#ffffff',
scale: window.devicePixelRatio || 1
});
canvas.toBlob(blob => {
if (!blob) throw new Error('Canvas export returned no data');
const link = document.createElement('a');
link.download = 'google-map.png';
link.href = URL.createObjectURL(blob);
link.click();
URL.revokeObjectURL(link.href);
}, 'image/png');
});
</script>
</body>
</html>
Replace the placeholder map initialization with your Google Maps code. Keep the map element’s width and height explicit. If the map is still moving, wait for its implementation’s ready signal before calling html2canvas.
2. Wait for map tiles before capturing
A capture that starts while tiles are still arriving can contain blank or partial areas. A historical html2canvas issue discussion suggested listening for the Google Maps tilesloaded event. Treat that as a timing technique to validate with your map version, not as a CORS fix or a guarantee.

function captureAfterTiles(map) {
return new Promise((resolve, reject) => {
const timeout = setTimeout(() => reject(new Error('Timed out waiting for map tiles')), 15000);
const listener = google.maps.event.addListenerOnce(map, 'tilesloaded', async () => {
clearTimeout(timeout);
try {
const element = document.querySelector('#map');
const canvas = await html2canvas(element, {
useCORS: true,
allowTaint: false
});
resolve(canvas);
} catch (error) {
reject(error);
}
});
});
}
Some applications create or replace the map more than once. Attach the listener to the current map instance, and remove or replace old listeners when navigating between views. If your map wrapper does not expose tilesloaded, combine a documented ready callback with a bounded delay and verify the output.
3. Why Google Maps tiles disappear or exports fail
The main problem is cross-origin canvas security. When JavaScript draws foreign-origin pixels without CORS approval, the canvas becomes tainted. Reading it with toDataURL(), toBlob(), or getImageData() then raises a SecurityError. MDN describes this rule in its CORS enabled image guide.
useCORS requests permission; it does not grant it
const canvas = await html2canvas(document.querySelector('#map'), {
useCORS: true,
allowTaint: false
});
useCORS: true asks html2canvas to load images using CORS. The image server must respond with a suitable Access-Control-Allow-Origin header. You cannot add that header from browser JavaScript, and html2canvas cannot override the server’s policy.
Keep allowTaint distinct from exportability
The documented default is allowTaint: false. With that setting, html2canvas skips resources it predicts would taint the canvas. Setting allowTaint: true may allow drawing such resources, but a tainted canvas still cannot be exported. Use it only when you do not need pixel data, which is uncommon for a download workflow.
Use a proxy only when you control and authorize it
html2canvas documents a proxy option for resources that can be fetched through an application-controlled proxy. The proxy must be designed for the specific resources and comply with their access rules. A proxy does not make browser restrictions disappear.
const canvas = await html2canvas(mapElement, {
useCORS: true,
proxy: '/image-proxy'
});
Do not build an open proxy. Validate destinations, restrict methods, apply timeouts, and avoid forwarding credentials.
4. Capture only the map or one element
Capture the map container instead of the whole document whenever possible. This reduces work, avoids unrelated cross-origin images, and lowers the chance of hitting canvas-size limits.
const mapElement = document.querySelector('#map');
const canvas = await html2canvas(mapElement, {
width: mapElement.clientWidth,
height: mapElement.clientHeight,
x: 0,
y: 0,
scale: 1,
backgroundColor: '#fff',
logging: true
});
For a high-resolution export, increase scale carefully. The resulting pixel dimensions are approximately CSS width × scale by CSS height × scale.
5. Chrome and Safari: what to compare
Both browsers are listed as supported by html2canvas, but that support does not promise identical Google Maps output. Test the same map state in both browsers and record:
- Whether every tile is visible before capture.
- Whether the export omits tiles or throws
SecurityError. - Whether the map is shifted, cropped, or scaled.
- The CSS dimensions, device pixel ratio, and requested
scale. - Whether tile responses include the required CORS headers.
If the map is present but shifted, inspect the captured element’s dimensions, positioning, transforms, and map state in a minimal reproduction. A historical report described offset output in an early html2canvas version; it does not establish that current releases reproduce the problem.
6. Canvas size and performance limits
Large full-page or high-scale captures can fail independently of map loading. The html2canvas FAQ gives rough evergreen-browser guidance of about 32,767 pixels for a maximum dimension in Chrome/Chromium and desktop Safari, and about 268 million pixels of total area for Chrome/Chromium. These are estimates that vary by GPU, operating system, browser version, and device. Oversized canvases can be blank or only partially rendered.
- Capture the map element rather than the entire page.
- Keep
scaleat 1 until correctness is established. - Calculate width × height before allocating a very large canvas.
- Split a very large map into smaller regions if your workflow allows it.
- Use
toBlob()instead of a huge base64 data URL for downloads. - Disable debug logging after diagnosing a problem.
function assertReasonableSize(element, scale) {
const width = Math.round(element.clientWidth * scale);
const height = Math.round(element.clientHeight * scale);
const pixels = width * height;
if (width > 32767 || height > 32767) {
throw new Error('Requested canvas dimension is too large');
}
if (pixels > 268000000) {
throw new Error('Requested canvas area may exceed browser limits');
}
}
7. Troubleshooting checklist
| Symptom | Likely cause | Fix |
|---|---|---|
| Blank map area | Tiles were not ready, or html2canvas skipped cross-origin images | Wait for the map’s ready or tilesloaded event; inspect CORS headers; use useCORS: true only when supported. |
SecurityError during export |
The canvas is tainted by a foreign-origin resource | Remove or replace the resource, obtain CORS permission from its server, or use an authorized proxy. allowTaint: true does not make export safe. |
| Map is cropped | The target element has unexpected dimensions or overflow | Set explicit width and height, capture the map element, and inspect computed styles and scroll position. |
| Map is shifted | Positioning, transforms, or map state changed during cloning | Freeze the map state, remove unnecessary transforms in a test case, and compare element bounds immediately before capture. |
| Only part of a large map renders | Canvas dimension or area limit | Reduce capture size or scale; split the capture; avoid full-page screenshots when the map alone is needed. |
| Capture works in one browser only | Different loading timing, resource policy, or rendering behavior | Compare network responses, device pixel ratio, dimensions, and readiness timing in both browsers. |
| Export returns no blob | Canvas allocation or rendering failed | Check console errors, reduce dimensions, and verify that the canvas has nonzero width and height. |
8. A repeatable diagnostic sequence
- Capture a plain same-origin colored
div. If that fails, fix your html2canvas setup first. - Capture the map at scale 1 with a fixed element size.
- Wait for the map’s documented ready signal, then try again.
- Open DevTools and inspect tile responses for
Access-Control-Allow-Origin. - Temporarily remove overlays, markers, controls, and other images to identify the resource that taints or shifts the result.
- Try Chrome and Safari with the same viewport and device pixel ratio.
- Increase scale only after the basic export is reliable.
9. Or skip the browser setup
If you need a server-side screenshot instead of reconstructing the map DOM in each browser, ScreenshotNeo accepts one GET request and returns PNG, JPEG, WebP, or PDF. Its capture pipeline accepts cookie and consent banners like a visitor, then removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers.

See the ScreenshotNeo API documentation for the complete option list, including full-page and selector captures, device presets, retina scale, waits, custom CSS and JavaScript, request blocking, headers, cookies, user agents, geolocation, caching, signed links, asynchronous jobs, bulk capture, and usage reporting.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
Python
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)
Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const buffer = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', buffer);
ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account.
10. FAQ
Can html2canvas capture the Google Maps basemap reliably?
Only when the map’s resources are readable under browser CORS rules and the map has finished rendering. Browser support alone is not a fidelity guarantee.
Does useCORS: true bypass Google Maps restrictions?
No. It requests CORS loading. The resource server must opt in with the appropriate response header.
Is tilesloaded required?
No. It is a useful readiness signal to test when captures start too early. It does not resolve cross-origin permission or canvas-size limits.
Why does a screenshot look correct on screen but fail to download?
The browser can display cross-origin pixels while still forbidding JavaScript from reading them back from a tainted canvas.
Should I capture the entire page?
Usually no. Capturing the map element reduces processing and avoids unrelated images and oversized canvases.


