01 · Diagnose the problem

Loading web fonts reliably in HTML-to-image jobs

A browser can finish parsing and painting before the intended font is usable. The fallback changes line breaks, card height and alignment even if the font swaps in a few milliseconds later.

3 min readPublished 2026-08-11Updated 2026-08-12

What you actually see

Production images wrap one word earlier than local output, use a system font, or shift between otherwise identical captures.

Reproduce it

01Throttle the font response and capture once at DOMContentLoaded, once after load, and once after document.fonts.ready.
02Call document.fonts.check('600 48px Inter', 'Invoice 1042') with representative glyphs; a family being loaded does not prove every requested face or glyph is available.
03Inspect the font response's CORS and content-type headers from the same origin policy the production renderer uses.

02 / Do it yourself

Wait for the exact face, then capture

Declare the exact face, wait on the CSS Font Loading API, verify it with representative text and only then capture.

html-to-image.mts

await page.setContent(html, { waitUntil: "load" });

await page.evaluate(async () => {
  await document.fonts.ready;
  const wanted = '600 48px "Report Sans"';
  if (!document.fonts.check(wanted, "Quarterly revenue €12,450")) {
    throw new Error(`Font did not load: ${wanted}`);
  }
});

await page.screenshot({ path: "card.png", type: "png" });

03 / Where it breaks

Why the fallback font still wins

The call above is small. Everything around it is the system — and the system is what you would be signing up to own.

CORS blocks the font

The CSS can be readable while the font request is rejected. The response must allow the controlled document origin, or the browser keeps the fallback.

The wrong weight is available

Loading the family at 400 does not satisfy a 600 face. Synthetic bold can look different across browser and platform versions.

The font lacks a glyph

A Latin sample can pass while currency, CJK or emoji still falls back. Check with text representative of the artifact.

A font is installed only locally

System fonts make a development laptop look correct while a minimal production image uses another fallback. Ship or fetch every non-generic face explicitly.

Keep the DIY version when

The template uses a generic system stack and small metric differences do not affect the artifact.
All fonts are data URLs inside the controlled HTML and the same Chromium build produces every image.

04 / The recipe

Load fonts in HTML to image

Send the HTML rather than hosting a temporary page. The worker waits for document.fonts.ready during its settle phase and applies the same outbound policy to font subresources.

Capture settings

Enter the source, choose your options, then run the capture.

Result

Your capture will appear here and stay in view.

waiting

No result yet

Complete the settings and run the tool. Images, PDFs, text, and video all preview in this panel.

Send this exact request

cURL, TypeScript and Python are generated from the same configuration as the demo.

curl --fail-with-body "https://api.pagecapture.dev/v1/take" \
  -H "X-Access-Key: $PAGECAPTURE_KEY" \
  -H "Content-Type: application/json" \
  --data '{"html":"<main id=\"card\" style=\"font:600 48px/1.15 system-ui;padding:72px\"><p style=\"font-size:16px\">Quarterly report</p><h1>Revenue €12,450</h1></main>","format":"png","viewport_width":1200,"viewport_height":630}' \
  -o capture.png

05 / Output, limits, cost, failures

What a font-safe HTML-to-image job returns

Output

A PNG from an isolated HTML document after fonts and pending images receive a bounded settle window.

Cost

One successful, non-cached capture costs one credit. Failures, including platform failures, cost zero; cache hits cost zero.

1 creditper successful non-cached capture

Limits

Remote fonts must be reachable over HTTPS and pass the same egress policy as every subresource.
The settle window is bounded; a font server that never completes cannot hold the job forever.
The API cannot license or redistribute a commercial font for you.

Common errors

matched_failed_requestnever billed

A configured failed-request policy matches the font URL that did not load.

HTTP 500 · terminal

timeout_errornever billed

Navigation or another readiness rule exhausts the capture budget.

HTTP 500 · retryable

06 / Take it for a run

Try it against your own page

Swap the example for a page you care about. The runner keeps every option from this guide, and carries the whole configuration into the playground — no retyping, no starting over.

Return to the configured runner

07 / Verification

Tested and reviewed

Written by PageCapture Engineering. Reviewed by PageCapture render maintainers. Verified 2026-08-12 by running the published code against a fixture.

The recipe is normalized and generated snippets are syntax-checked; font readiness claims are tied to the worker settle implementation and CSS Font Loading API.

engine-crunknown-pwunknown-f2026-07-1-b2026-08-1Status Inline HTML capture reference Editorial method

Sources and verification basis

Sources support the browser and API behaviors named above. PageCapture-specific limits and billing are taken from the public contract; external sources are used for the underlying browser behavior.

CSS Font Loading APICSS Working Group
Defines FontFaceSet.ready and check().
HTML to image APIPageCapture
Provides the runnable inline-HTML surface used by the recipe.

08 / Continue from here

Related guides and reference

HTML to image

Run inline markup and inspect the artifact.

Readiness controls

Add an application marker when font readiness alone is insufficient.

Subresource egress

Remote font URLs cross the same network boundary as the page.

Render the markup now

Paste the card and see which face the renderer actually used, before wiring the template into your app.