# Web fonts in HTML to image: the 0.5 s wait

> One number from 405 renders: when a page asks for its web font late, captures before 0.5 s showed the wrong font. The fix is a marker, not a longer delay.

One number by Serghei Pogor, founder of CurlShot (https://curlshot.com/about/serghei-pogor). Published 19 November 2026. Page for people: https://curlshot.com/blog/html-to-image-web-font-wait

When the page's own CSS names the font, CurlShot needs no wait: 50 of 50 test renders drew the web font even when it took 6 s to arrive. A font the page asks for after load is the risk: on a page that asked 0.4 s after load, 24 of 30 renders captured before 0.5 s showed the fallback font or invisible text, and 0 of 90 captured after. Chromium 153, 12 November 2026.

## Key facts

- The renderer of CurlShot has no font wait of its own. Its browser library waits for the page's font set to settle before each screenshot, so a font already requested is waited for: 50 of 50 renders drew it, even at 6 s.
- font-display decides what a late font looks like. optional drew the web font in 0 of 25 renders, and fallback in 15 of 15 with a 1 s font but 0 of 10 with a 3 s or 6 s one.
- For a page that asks for its font 0.4 s after load, html captured before 0.5 s showed the wrong font in 24 of 30 renders (80%). From 0.5 s it was 0 of 90, whether the font answered in 0, 300 or 1,000 ms.
- The 0.5 s belongs to the page, not the font: a page that asks at 1.2 s was wrong in 15 of 15 renders up to a 1 s delay and right in 15 of 15 from 1.5 s.
- An address sent as url went through the settle step and drew the late font in 20 of 20 renders with no delay. html skips that step, and wait_until=networkidle caught the 0.4 s page (15 of 15) but not the 1.2 s one (0 of 5).
- The fix that does not depend on timing: set a marker when document.fonts.load() resolves and wait_for_selector on it. A marker set by document.fonts.ready worked in 11 of 25 renders only.

## The one number
CurlShot drew the web font in 90 of 90 renders that were captured 0.5 s or more after load, on a page that asks for its font 0.4 s after load. Captured before 0.5 s, 24 of 30 renders (80%) showed the fallback font or invisible text. The page's own timing sets the number: a page that asks at 1.2 s needed 1.5 s.
## A font named in the page's CSS needs no wait
Test pages that name the font in their own CSS, a font that answers after 0 ms to 6,000 ms, html sent with no delay. Renders that drew the web font, out of 5.
| font-display | at once | 300 ms | 1,000 ms | 3,000 ms | 6,000 ms |
| --- | --- | --- | --- | --- | --- |
| auto | 5 of 5 | 5 of 5 | 5 of 5 | 5 of 5 | 5 of 5 |
| swap | 5 of 5 | 5 of 5 | 5 of 5 | 5 of 5 | 5 of 5 |
| fallback | 5 of 5 | 5 of 5 | 5 of 5 | 0 of 5 | 0 of 5 |
| optional | 0 of 5 | 0 of 5 | 0 of 5 | 0 of 5 | 0 of 5 |
CurlShot has no font wait of its own. The capture call of its browser library waits for the page's font set to settle, so a font the page has already asked for is waited for, up to 6.5 s here. The default and swap drew the web font in 50 of 50 renders. optional drew it in 0 of 25. fallback drew it in 15 of 15 when the font answered within 1 s and in 0 of 10 when it took 3 s or 6 s.
## A font the page asks for late
The page switches to the web font 0.4 s after the load event. html was sent with a delay of 0 to 3 s. Renders that drew the web font, out of 5.
| Font answers in | none | 0.25 s | 0.5 s | 0.75 s | 1 s | 1.5 s | 2 s | 3 s |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| at once | 0 of 5 | 0 of 5 | 5 of 5 | 5 of 5 | 5 of 5 | 5 of 5 | 5 of 5 | 5 of 5 |
| 300 ms | 0 of 5 | 1 of 5 | 5 of 5 | 5 of 5 | 5 of 5 | 5 of 5 | 5 of 5 | 5 of 5 |
| 1,000 ms | 2 of 5 | 3 of 5 | 5 of 5 | 5 of 5 | 5 of 5 | 5 of 5 | 5 of 5 | 5 of 5 |
Before 0.5 s: 24 of 30 renders had the wrong font. From 0.5 s: 0 of 90. The font answering in 0, 300 or 1,000 ms made no difference to where the line fell, because the browser waits for a font it has asked for, and cannot wait for one it has not.
## The number moves with the page
The same page, asking for its font 1.2 s after load, font answering in 300 ms.
| Delay | none | 0.5 s | 1 s | 1.5 s | 2 s | 3 s |
| --- | --- | --- | --- | --- | --- | --- |
| Drew the web font | 0 of 5 | 0 of 5 | 0 of 5 | 5 of 5 | 5 of 5 | 5 of 5 |
Up to 1 s: 15 of 15 wrong. From 1.5 s: 0 of 15. A fixed delay is the page's asking time plus a margin, so it is a guess about a page you may not control.
## What the other waits did
| How the page was sent | Page asks at 0.4 s | Page asks at 1.2 s |
| --- | --- | --- |
| html, wait_until=networkidle | 15 of 15 | 0 of 5 |
| An address (url), nothing set | 20 of 20 | not tested |
An address goes through the settle step: the renderer waits for the network to go quiet and the picture to stop changing, so it saw the late font in 20 of 20 renders. html input skips that step. wait_until=networkidle for html waits for 500 ms without requests, which a request at 0.4 s breaks and one at 1.2 s does not.
## The fix: wait for the font itself
Let the page say when the font is there, and wait for that with wait_for_selector.
```html
<script>
document.fonts.load('700 64px "Lab Face"').then(() => {
  document.body.dataset.fonts = "ready";
});
</script>
```
```bash
# Needs jq. The key stays in the ACCESS_KEY variable on your server.
jq -n --rawfile html card.html \
  '{html: $html, viewport_width: 1200, viewport_height: 630, wait_for_selector: "body[data-fonts=ready]"}' |
  curl -X POST "https://curlshot.com/api/v1/screenshot" \
    -H "X-Access-Key: $ACCESS_KEY" \
    -H "Content-Type: application/json" \
    -d @- \
    --output card.png
```
| Marker set by | Drew the web font (html input) | Drew the web font (address input) |
| --- | --- | --- |
| document.fonts.ready | 11 of 25 | 25 of 25 |
| document.fonts.load() | 21 of 25, the rest timed out at 30 s | 24 of 25 |
document.fonts.ready resolves when no font is loading, which is true before a late request is made, so it marks too early. The first run of document.fonts.load() had 4 renders time out at 30 s while the host was heavily loaded; the same cells run again with a 60 s timeout drew the web font in 15 of 15.
## How it was run
On 12 November 2026. Each case is five renders. The real renderer process of the product ran on a Linux server (Chromium 153.0.8010.12, Playwright 1.63.0, an 800 x 300 window) and was sent each page as html, or as an address on a local server. A local server answered the font file (a 2 MB bold serif) after a set time. Each picture was compared with three reference pictures of the same page: the web font, the fallback font and invisible text. 405 renders in all. The host was shared and busy, so times in milliseconds are medians and not a speed test. The test pages hold one heading and a line of text; a real page with many fonts, weights and subsets may take longer to ask for them all. PDF output was not tested.

## Questions

### Why does my HTML to image render show the wrong font?

Most likely the page asks for the font after the capture has started. A font named in the page's CSS is waited for: 50 of 50 renders drew it, even at 6 s. A font a script requests later is not: 24 of 30 renders captured within 0.5 s of load showed the fallback or invisible text. Also check font-display: optional never swaps in the font.

### Does a delay fix web fonts in a screenshot?

Only if it is longer than the time the page takes to ask for the font. On the 0.4 s test page every delay from 0.5 s worked (90 of 90), on the 1.2 s page it took 1.5 s. The font's own download time did not matter, because the browser waits for a font it has asked for. A marker is safer than a number you have to guess.

### Do I need wait_until=networkidle for fonts?

Not for fonts named in the page's CSS. For html input it caught a font requested 0.4 s after load (15 of 15) but not one requested at 1.2 s (0 of 5), because it waits for 500 ms without requests and the later request came after that quiet spell.

### How do I wait for a web font in a screenshot API call?

Have the page set an attribute when document.fonts.load() resolves, then send wait_for_selector with that attribute. In the test it drew the web font in 15 of 15 renders on a quieter host, with the font answering after 0, 1,000 or 3,000 ms. Do not use document.fonts.ready for this: it resolved before a late request in most renders (11 of 25 drew the font).

### Which font-display value is safe for HTML to image?

auto and swap drew the web font in 50 of 50 renders. fallback drew it when the font arrived within 1 s but not when it took 3 s or 6 s, and optional drew the fallback every time (0 of 25). If the picture matters more than the page's first paint, use swap in the HTML you send to CurlShot.

## Sources

1. MDN Web Docs, "font-display": https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display (checked 12 November 2026)
2. MDN Web Docs, "FontFaceSet: ready property": https://developer.mozilla.org/en-US/docs/Web/API/FontFaceSet/ready (checked 12 November 2026)
3. MDN Web Docs, "FontFaceSet: load() method": https://developer.mozilla.org/en-US/docs/Web/API/FontFaceSet/load (checked 12 November 2026)

## Go deeper

- [HTML to image tool](https://curlshot.com/tools/html-to-image)
- [Open Graph image generator](https://curlshot.com/tools/open-graph-image-generator)
- [Waiting and timing](https://curlshot.com/docs/waiting)
- [HTML and Markdown input](https://curlshot.com/docs/html-and-markdown)
- [Pricing](https://curlshot.com/pricing)

## Read next

- [HTML to image: six templates you can copy](https://curlshot.com/blog/html-to-image-templates.md): Six copyable HTML and CSS templates: social card, certificate, receipt, quote card, ticket and stat card, with sizes and the rules that make them render right.
- [From html-to-image to an API: migration notes](https://curlshot.com/blog/migrate-from-html-to-image.md): Every html-to-image option and what replaces it in a screenshot API, plus a test of eight pages: the library and html2canvas against a real browser.
- [Why website screenshots look wrong, and the fixes](https://curlshot.com/blog/why-website-screenshots-look-wrong.md): A field guide to 11 ways a website screenshot goes wrong, from blank lazy images to cookie banners and cut-off pages, with the cause and the fix for each.
