Skip to content

Commit 84221c1

Browse files
hjl12345hjl12345
committed
docs: add CORS & external resources guidance to README
External stylesheets (Font Awesome, Google Fonts, etc.) often load font files from CDNs. Even though the page renders correctly in the browser, SnapDOM's Canvas-based capture fails to draw those fonts or icons unless the resources are served with proper CORS headers. This is due to Canvas security policies that block reading cross-origin binary data — a behavior we confirmed while testing icon fonts with embedFonts:true. Add a new "CORS & External Resources" section under Usage that explains: - Why CORS headers are required for external fonts and icons. - How to fix it by adding `crossorigin="anonymous"` to the `<link>` tag. - That same-origin assets (e.g., localhost) do not need this attribute. This addresses a common pitfall for new users and reduces debugging overhead, especially for those coming from html2canvas or dom-to-image.
1 parent e1fb59e commit 84221c1

1 file changed

Lines changed: 23 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -191,6 +191,29 @@ const blob = await snapdom.toBlob(el);
191191
document.body.appendChild(png);
192192
```
193193

194+
## CORS & External Resources
195+
196+
When capturing elements that reference **external stylesheets** (e.g., Google Fonts, Font Awesome, or any CDN‑hosted CSS), you **must** ensure that the resources are served with proper CORS headers. Otherwise, the captured image may lack the expected fonts or icons, even though they render correctly in the browser.
197+
198+
### Why is this needed?
199+
200+
- Browsers block JavaScript (including SnapDOM) from reading the binary data of cross‑origin fonts or images unless the server explicitly allows it via `Access-Control-Allow-Origin`.
201+
- SnapDOM relies on Canvas, which enforces strict CORS policies — unlike the browser's rendering engine, which is more permissive for on‑screen display.
202+
203+
### How to fix it
204+
205+
Add the `crossorigin="anonymous"` attribute to the `<link>` tag when loading external stylesheets:
206+
207+
```html
208+
<link
209+
rel="stylesheet"
210+
href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css"
211+
crossorigin="anonymous"
212+
/>
213+
```
214+
215+
> **Note**: If you are hosting the fonts or assets **on the same origin** as your page (e.g., using a local server like `http://localhost`), you **do not** need to add `crossorigin` – the browser treats them as same‑origin and allows full access.
216+
194217
## Documentation
195218

196219
The full reference lives on **[snapdom.dev/docs](https://snapdom.dev/docs/)** — kept there so it stays in sync and searchable:

0 commit comments

Comments
 (0)