An API for fast, beautiful web fonts

An update on the Google Fonts CSS API—how it works, how to use it, and how it can efficiently deliver your web fonts.

W

web.devweb.dev

·

Web fonts without the weight

Web fonts used to be a heavy compromise: you either served an image of your text or loaded a full typeface before the page could render, complete with styles and character sets you may never use. The Google Fonts CSS API has evolved alongside the technology to change that equation. Originally pitched as a way to speed up the web by caching fonts across sites, that benefit is gone in an era of partitioned browser caches. What remains is something arguably more useful: an API that serves only the font data a page actually needs, in the format the user's browser supports, all via a single stylesheet link.

One line to load fonts

Using the API is deliberately low-effort. Per its documentation, no programming is required—just add a stylesheet link to your HTML document and refer to the font in your CSS:

<link href="https://fonts.googleapis.com/css2?family=Roboto+Mono&display=swap" rel="stylesheet" />

When a request comes in, the API responds in one of two ways. If you've requested common parameters it already has files for, it immediately returns CSS pointing to those cached fonts. Otherwise, it subsets your font on the fly using HarfBuzz and returns CSS referencing those newly generated files.

Subsetting is the point

Font files are genuinely large. One weight of Noto Sans Japanese in WOFF2 approaches 3.4MB. Shipping that to every visitor is a serious performance tax. The API's answer is to create small subsets of only the characters your content needs, either through the text parameter or through automatic unicode-range support.

With the text parameter, you request only the characters you plan to display:

<link href="https://fonts.googleapis.com/css2?family=Roboto+Mono&display=swap&text=RobtMn" rel="stylesheet" />

A chart with a character count of basic Latin, basic Greek, and extended Greek.

The API also injects unicode-range into the CSS it returns (where the browser supports it), so fonts are downloaded only when a page actually renders a character in that range. This works especially well for languages beyond Latin. Greek, Cyrillic, and other scripts can be broken into targeted slices, keeping each font download to just the glyphs in use.

A chart with a character count of basic Latin, extended Latin, Korean and Japanese.

CJK fonts are where this pays off. Those typefaces cover 15–20 times the number of characters of a Latin font, making them enormous by default. Using the CSS API's unicode-range built-ins can cut transferred bytes by roughly 90%. Adding the text parameter trims even further. In one example, specifying the Japanese word "こんにちは" brings a Noto Sans JP download down to a fraction of what self-hosting the entire WOFF2 would require:

Graph with comparison of different methods of downloading Noto Sans JP.

The API also negotiates format for you: WOFF2 when the browser supports it, older formats when it doesn't, and it strips unneeded data—like hinting for browsers that don't require it—to keep every file lean.

Built for what's next

The Google Fonts team contributes to W3C standards like WOFF2 and the ongoing Incremental Font Transfer effort, which streams font data on demand rather than downloading whole files. Because your page asks the API for fonts rather than hosting files, those improvements arrive without any change on your end. New formats, new browser support—the API handles it all transparently.

Variable fonts, trimmed to fit

Variable fonts pack multiple design axes into a single file, which is powerful but can nearly double an already large download. The CSS API can serve just the portion of a variable font your site uses, whether that's a single value on an axis, a range, or multiple axes and families in one request. That flexibility lets you adopt variable fonts without absorbing their full file size.