A web font changes more than typography. It adds network requests, affects when text becomes visible, can shift layout when metrics change, and may send a visitor’s connection metadata to another service. The good version of “add a Google Font” begins with a design and privacy decision, not a copied <link> tag.

Before loading anything, define the font budget

  • Which family is used for body text, headings, code, or branding?

  • Which real weights and italic styles appear in the design system?

  • Which Unicode writing systems must be readable on this page?

  • Can a system-font stack meet the design with zero font requests?

  • Does policy permit a browser to contact Google-hosted font domains?

  • What LCP, CLS, transfer, and request budget must the page maintain?

  • Will the font be hosted remotely or copied and served under its license from your own origin?

Option A: use the Google Fonts CSS2 API

index.htmlhtml
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
 
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link
    rel="stylesheet"
    href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap"
  >
 
  <link rel="stylesheet" href="/css/site.css">
  <title>Readable type</title>
</head>
<body>
  <main>
    <h1>Readable engineering notes</h1>
    <p>The interface remains usable while the web font loads.</p>
  </main>
</body>
</html>

Every line should earn its request

  • The CSS2 endpoint uses HTTPS and encodes the family plus weights 400, 600, and 700.

  • display=swap asks the browser to show fallback text immediately, then swap when the font is ready.

  • The Google stylesheet and font binaries use different origins.

  • crossorigin is required on the gstatic preconnect so the connection can be reused for CORS font requests.

  • Preconnect consumes sockets and handshake work; keep it limited to origins used early on the page.

  • The project stylesheet comes after the font request and contains the actual font-family declaration.

Apply the family with resilient fallbacks

css/site.csscss
:root {
  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont,
    "Segoe UI", sans-serif;
  font-synthesis: none;
}
 
body {
  margin: 0;
  font-size: 1rem;
  line-height: 1.6;
}
 
h1 {
  font-size: clamp(2rem, 5vw, 3.5rem);
  font-weight: 700;
  line-height: 1.1;
}

Fallback is the first render, not an afterthought

  • The custom family name comes first, followed by system UI alternatives and a generic sans-serif fallback.

  • Different platforms may select different system fonts, so test layout with the web font blocked.

  • font-synthesis:none prevents browsers from inventing bold/italic faces; request every style the design truly uses.

  • Unitless line-height scales with text size and usually behaves better across responsive/accessible zoom.

  • clamp() bounds the heading size while allowing responsive growth.

  • A fallback with similar metrics reduces reflow when the web font swaps in.

Request only real styles and weights

Two families and italic styleshtml
<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Inter:ital,wght@0,400;0,700;1,400&family=Source+Code+Pro:wght@400;600&display=swap"
>

The CSS2 query axes must be sorted

  • Family names replace spaces with + in the URL.

  • Axis names are listed alphabetically (ital,wght).

  • Tuple values are sorted numerically: normal 400, normal 700, then italic 400 according to tuple ordering.

  • Each requested family/style/weight can add CSS rules and font resources.

  • Do not request weights that CSS never uses or fake a missing weight through synthesis.

  • A monospace family should still end with a generic monospace fallback in CSS.

Variable fonts can replace many static files

Variable weight rangehtml
<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Roboto+Flex:wght@300..700&display=swap"
>

A range is useful only when the design uses it

  • 300..700 requests a continuous weight axis range.

  • Variable fonts can reduce separate files while one file may be larger than one static face.

  • Requesting the entire axis range “just in case” wastes bytes.

  • Check browser support for the features/targets your product requires.

  • Avoid animating font axes without performance testing and respect reduced-motion preferences where motion is involved.

  • Inspect the returned CSS because Google may serve different optimized formats/subsets by user agent.

Unicode subsets and multilingual pages

Google Fonts CSS commonly uses unicode-range rules so the browser downloads only font subsets needed for characters on the page. That can be efficient, but your chosen family must actually support every script and symbol the product promises. Test real names, technical symbols, numerals, punctuation, and localized content rather than a Latin-only marketing sentence.

  • Declare the document language and language changes accurately.

  • Choose families with glyph coverage for all supported writing systems.

  • Expect additional subset downloads when content introduces another script.

  • Test combining marks, diacritics, emoji fallback, bidirectional text, and font shaping where relevant.

  • Never render missing-glyph boxes for critical information; retain appropriate system/generic fallbacks.

Understand font-display rather than choosing by habit

  • swap gives a very short block period and an effectively unlimited swap period; text appears quickly but can change metrics later.

  • block allows a longer invisible-text period and is rarely a good default for body copy.

  • fallback provides a short block and limited swap period, favoring stable fallback after a short opportunity.

  • optional gives the browser substantial discretion and may keep the fallback on slow connections.

  • The CSS API’s display parameter controls generated font-display; self-hosted fonts set the descriptor in @font-face.

  • Choose from product priorities and measurements: brand fidelity, readability, CLS, repeat visits, and network conditions.

Preload is narrower than preconnect

Preconnect prepares DNS/TCP/TLS to an origin. Font preload fetches one exact font resource early. With the Google-hosted CSS API, the final font URL is generated in a cross-origin stylesheet and can vary by browser/subset, so hard-coding a gstatic preload is brittle. Preload is more predictable when self-hosting a known, critical WOFF2 file.

Self-hosted critical font preloadhtml
<link
  rel="preload"
  href="/fonts/inter-latin-400.woff2"
  as="font"
  type="font/woff2"
  crossorigin
>

Preload only what the first view certainly uses

  • The URL must exactly match the URL used by @font-face.

  • as="font", the MIME type, and CORS mode help the browser reuse the preload.

  • Preloading an unused weight/subset competes with CSS, scripts, images, and other critical resources.

  • A preload warning often means the resource was not consumed promptly or did not match request credentials.

  • Measure priority changes in a production-like waterfall rather than preloading every font file.

Option B: self-host the font files

Self-hosting keeps font requests under your origin/CDN policy and gives you control over caching and versioning. It also makes you responsible for obtaining files lawfully, preserving license notices, generating/choosing correct subsets, serving correct headers, updating vulnerable tooling, and avoiding accidental glyph loss.

Choose the hosting model deliberately

  • Choose the Google-hosted API when policy permits it and managed format/subset delivery is worth the third-party request.

  • Choose self-hosting when third-party connection policy, deterministic asset control, offline use, or deployment architecture requires it.

  • Compare real transfer bytes, cache behavior, CDN distance, subsets, operational ownership, and privacy—not folklore about one option always being faster.

  • Whichever model wins, preserve readable fallbacks and verify failure behavior.

  • Record the choice so future developers do not load the same family through both paths.

css/fonts.csscss
@font-face {
  font-family: "Inter";
  src: url("/fonts/inter-latin-400.woff2") format("woff2");
  font-style: normal;
  font-weight: 400;
  font-display: swap;
}
 
@font-face {
  font-family: "Inter";
  src: url("/fonts/inter-latin-700.woff2") format("woff2");
  font-style: normal;
  font-weight: 700;
  font-display: swap;
}

Each face declaration must match the binary

  • Use WOFF2 for modern web delivery unless browser requirements demand another format.

  • The declared family, style, and weight must describe the actual file.

  • A Latin-only subset is not suitable for users whose content needs other scripts.

  • Use content-hashed filenames or a versioned path with long-lived immutable caching.

  • Serve font/woff2, compression/caching headers, and CORS headers appropriate to the asset origin.

  • Keep the font license and upstream version/provenance with the source/deployment records.

Reduce layout shift with compatible metrics

font-display:swap protects text visibility but can still shift lines when fallback and web-font metrics differ. Start with a visually compatible fallback. For self-hosted or locally defined fallback faces, advanced @font-face descriptors such as size-adjust, ascent-override, descent-override, and line-gap-override can align metrics—after measuring the actual fonts.

css/fallback-metrics.csscss
@font-face {
  font-family: "Inter Fallback";
  src: local("Arial");
  size-adjust: 107%;
  ascent-override: 90%;
  descent-override: 22%;
  line-gap-override: 0%;
}
 
body {
  font-family: Inter, "Inter Fallback", sans-serif;
}

Metric values are font-pair-specific

  • The percentages shown are illustrative, not universal values for Inter and Arial.

  • Measure cap height, ascent, descent, and line gap with trusted tooling and real browser tests.

  • Incorrect overrides can clip glyphs or create worse layout.

  • Check multiple scripts, font sizes, weights, zoom levels, and operating systems.

  • Use field CLS and visual regression evidence before declaring the fallback matched.

  • A Google-hosted font request discloses connection metadata such as IP address and user-agent information to Google infrastructure.

  • Google Fonts states that requests are separated from other Google data and not used to create end-user profiles or targeted advertising; review the current policy directly.

  • Your legal/organizational obligations can still require disclosure, assessment, consent, or self-hosting depending on jurisdiction and context.

  • Do not defer font loading behind consent without designing a stable, readable fallback state.

  • Self-hosting reduces third-party font requests but does not automatically make the rest of the page privacy-compliant.

  • Document vendor, purpose, data flow, retention statements, and fallback behavior with the site’s privacy owner.

Content Security Policy for remote fonts

Content-Security-Policy response headerhttp
Content-Security-Policy: default-src 'self'; style-src 'self' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src 'self' data:; script-src 'self'; object-src 'none'; base-uri 'self'

Allow only the resources the page needs

  • The stylesheet endpoint belongs in style-src; font binaries belong in font-src.

  • Do not add broad wildcards or unsafe-inline merely to make a font request work.

  • The example is not a complete policy for every application; merge requirements without weakening existing controls.

  • Prefer an HTTP response header so policy covers the document consistently.

  • Test report-only mode and browser console violations before enforcement.

  • Self-hosted fonts can remain under `'self' when served from the same origin.

Do not use CSS @import for the critical font

Avoid for primary page fontscss
/* This delays discovery behind the main stylesheet. */
@import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap");

  • The browser must fetch and parse the containing stylesheet before discovering an @import.

  • An HTML <link rel="stylesheet"> is visible to the preload scanner earlier.

  • Imports must precede most other CSS rules, creating avoidable ordering constraints.

  • Bundlers may transform imports, but verify the actual production HTML/CSS waterfall.

  • Keep font-loading policy centralized rather than scattered across component stylesheets.

Verify remote CSS and response headers

Any workstation with curlbash
curl -sSIL \
  -A "Mozilla/5.0" \
  "https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap"
HTTP/2 200
content-type: text/css; charset=utf-8
cache-control: private, max-age=86400

A 200 response is only transport evidence

  • Quoting prevents &display=swap from being interpreted by the shell.

  • The user-agent matters because the service can return browser-appropriate CSS/font formats.

  • Inspect redirects, content type, cache policy, and CSP/CORS behavior.

  • Do not infer page performance or glyph coverage from one HEAD/header response.

  • Browser developer tools reveal the actual CSS and font requests for the real page and user agent.

Browser verification workflow

  1. Open a clean profile or private window and disable the cache in developer tools.

  2. Record a network trace on a throttled mobile connection and reload the page.

  3. Filter for font/CSS requests and confirm only intended families, styles, weights, and subsets load.

  4. Block the font origins/files and ensure all text remains visible, readable, and correctly laid out.

  5. Inspect computed styles to confirm the intended face is actually rendered rather than silently falling back.

  6. Measure LCP, CLS, text visibility, request count, compressed bytes, and repeat-view caching.

  7. Test representative languages, zoom, high contrast/forced colors where applicable, and low-end devices.

  8. Repeat against the production build/CDN because development delivery can hide cache and CSP behavior.

Automate the loaded-font assertion carefully

font-check.jsjavascript
async function verifyPrimaryFont() {
  await document.fonts.ready;
 
  if (!document.fonts.check("400 16px Inter")) {
    console.warn("Inter 400 did not load; the fallback remains active.");
  }
}
 
verifyPrimaryFont();

The Font Loading API observes availability

  • document.fonts.ready resolves after fonts needed by the current document have settled.

  • check() tests whether text using the specified shorthand can render without initiating another load in the expected way.

  • A warning should not break the page; fallbacks are part of the design.

  • Automated availability does not prove the correct file, glyph coverage, visual quality, or low CLS.

  • Use telemetry sparingly and avoid collecting user content merely to diagnose fonts.

Common integration failures

  • Font never appears: inspect the generated CSS request, family spelling, requested weight/style, CSP, ad/privacy blocking, and browser console.

  • Mixed-content warning: replace old http://fonts.googleapis.com URLs with HTTPS and remove redirect-era snippets.

  • Only bold looks wrong: request the real bold weight or allow intentional synthesis; do not assume 400 contains 700.

  • Italic is fake: request the italic axis/style used by the design.

  • Text disappears briefly: choose an appropriate font-display policy and verify fallback rendering.

  • Layout shifts after load: choose a closer fallback and consider measured metric overrides/self-hosting.

  • Too many font files: audit families, weights, styles, scripts, preloads, and duplicated component imports.

  • CSP blocks CSS or WOFF2: allow the exact style/font origins in their respective directives.

  • Self-hosted font is 404 or rejected: inspect URL, deployment copy, MIME type, CORS, case sensitivity, and cache.

  • Some languages show boxes: the family/subset lacks required glyphs or the fallback chain is inadequate.

A production-ready font checklist

  • Family selection and license/provenance are recorded.

  • Only used styles, weights, ranges, and writing systems are requested.

  • All URLs use HTTPS and source quotes are valid ASCII delimiters.

  • Fallback content is immediately readable with the web font blocked.

  • Preconnect/preload choices are justified by a measured waterfall.

  • Remote-font privacy/vendor handling is approved, or files are self-hosted correctly.

  • CSP allows only required stylesheet/font origins.

  • Self-hosted files have correct declarations, MIME/CORS, caching, versioning, and subsets.

  • CLS, LCP, font bytes, request count, glyph coverage, and supported browsers/devices are tested.

  • Monitoring treats web-font failure as graceful degradation, not a blank-page event.

Official and primary references