sodcalculator

10 Tech How-To

Fix fonts that change when converting HTML to image

Guide 10-43560 · Updated · Step by step

Fonts that change when converting HTML to an image are almost always a missing-font or font-loading problem: the rendering engine (browser, headless Chrome, or screenshot tool) falls back to a substitute typeface because the one you specified isn’t installed or hasn’t loaded yet. The fix is to make sure the exact font is available to the rendering engine, and to force the engine to wait until it’s fully loaded before capturing the image.

Why the font changes in the first place

When you convert HTML to an image, the tool you use doesn’t just “take a picture” of what you see on screen. It re-renders the HTML in its own environment, which may be a headless browser, a server-side library, or a desktop app. That environment has its own set of installed fonts, its own font-loading behavior, and its own default fallback order.

If the font you used in your original HTML is a system font (like Arial, Times New Roman, or Calibri) and the rendering environment is a different operating system, that font won’t exist. The renderer then substitutes a default font, which is why your carefully chosen typeface suddenly looks like a generic serif or sans-serif.

If the font is a web font loaded via @font-face or Google Fonts, the problem is usually timing. The screenshot is taken before the font finishes downloading, so the renderer paints with a fallback font first. Many screenshot tools capture the page immediately after the DOM is ready, not after all resources are loaded.

How font rendering works in HTML-to-image tools

Most HTML-to-image tools fall into two categories:

  • Headless browser screenshots (e.g., Puppeteer, Playwright, Selenium): these actually load the page in a real browser engine and then capture it. They support web fonts, but you must wait for the document.fonts.ready promise or the load event before taking the screenshot.
  • Direct rendering libraries (e.g., html2canvas, dom-to-image, rasterizeHTML): these parse the HTML and draw it onto a canvas themselves. They do not use the browser’s layout engine, so they have very limited font support. They often cannot load web fonts at all and rely entirely on system fonts.

With direct rendering libraries, even if the font is installed on your machine, the library may not know its exact name or metrics. It might measure text with a different font, causing both the typeface and the line spacing to change.

How to fix it: make the font available

The first and most reliable fix is to ensure the font is installed on the machine that runs the conversion. If you’re using a headless browser on a server, install the font as a system font on that server. For a local script, install it on your own OS.

For web fonts, the fix is to embed the font as a base64 data URI directly in the CSS. This way, the font is part of the HTML itself and doesn’t require a separate network request. Example:

@font-face {
  font-family: 'MyFont';
  src: url(data:font/woff2;base64,AAA...==) format('woff2');
}

This works with headless browsers because the font data is already in the document. It does not work with direct rendering libraries that ignore @font-face entirely.

How to fix it: wait for the font to load

If you’re using Puppeteer or Playwright, add a wait before the screenshot:

  1. Navigate to the page.
  2. Call document.fonts.ready and await it.
  3. Optionally, call document.fonts.load('16px MyFont') to force a specific font to load.
  4. Take the screenshot.

In Puppeteer, that looks like:

await page.evaluateHandle('document.fonts.ready');
await page.screenshot({ path: 'out.png' });

If the font still doesn’t appear, check the browser’s network tab to see if the font file actually downloaded. A 404 or a CORS error will cause the font to fail silently, and the fallback will be used.

How to fix it: use a font that is always present

If you control the environment and cannot install new fonts, switch to a font that is universally available on the target OS. For example, Arial on Windows, Helvetica on macOS, and DejaVu Sans on Linux. But note that even “standard” fonts differ: Arial and Helvetica are not the same, and neither is exactly the same as Liberation Sans (the common Linux substitute).

A better approach is to use a font stack that lists the same visual style across all platforms:

font-family: 'Helvetica Neue', Arial, 'Liberation Sans', sans-serif;

This way, even if the exact font is missing, the renderer picks the closest available option, and the change is less noticeable.

Common problems and their specific fixes

  • Font is bold when it shouldn’t be: the renderer is synthesizing a bold weight because the actual bold file isn’t loaded. Use the exact font-weight in the @font-face declaration and load all weights you use.
  • Text is blurry or pixelated: the canvas is being scaled. Set the canvas dimensions to match the device pixel ratio, or increase the screenshot resolution.
  • Line spacing changes: the fallback font has different metrics. This is a symptom of the missing-font problem, not a separate issue. Fix the font availability and the spacing will return.
  • Font loads in a regular browser but not in the screenshot: the screenshot tool likely has JavaScript disabled or doesn’t execute it. Some tools have an option to enable JS; if not, switch to a headless browser.

Comparing the main tools

Here’s how the most common tools handle fonts:

  • Puppeteer/Playwright: full font support, including web fonts, if you wait for them. Best choice for reliable output.
  • html2canvas: no web font loading, relies on system fonts. You must install the font on the machine or embed it as a data URI (which it may still ignore). Often produces different text metrics.
  • dom-to-image: similar to html2canvas, but even less mature. Font support is inconsistent.
  • wkhtmltoimage: uses an old WebKit engine. Supports @font-face but has many rendering quirks. Prefer modern headless browsers.

If you need pixel-perfect output, a headless browser is the only reliable option. The direct rendering libraries are fine for simple layouts but will always be fragile with fonts.

Frequently Asked Questions

Why does the font change only in the image, not in my browser?

Because the image is rendered in a separate environment. Your browser has the font installed and loads web fonts automatically. The screenshot tool may be running on a different OS or may not wait for the font to load. The fix is to make the font available to that environment and to wait for it to be ready.

Can I embed the font directly in the HTML to avoid loading issues?

Yes, converting the font file to a base64 data URI and putting it in the CSS @font-face rule works for headless browsers. It increases the HTML size but guarantees the font is present. It does not work with html2canvas or similar canvas-based libraries.

What is the best free font to use for HTML-to-image that won’t change?

There is no single font that is guaranteed to be on every system. The safest approach is to use a font stack with common fallbacks, or to install the font on the server. For web fonts, use a widely available one like Roboto or Open Sans, but still embed it or wait for it to load.

Why does the text look bold or italic in the image when it’s not in the browser?

This happens when the renderer cannot find the exact font weight or style and synthesizes it. For example, if you use ‘Open Sans’ with font-weight: 400 but only the 700 weight file is loaded, the renderer may fake the bold. Load all the weights you use in your @font-face declarations.

Does increasing the image resolution fix font rendering issues?

No. Resolution affects sharpness, not which font is used. If the font is missing, a higher resolution will just show a sharper version of the wrong font. Fix the font availability first, then adjust resolution if needed.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →