json

Method 1: Using WordPress Font Library

In WordPress 7.0, the preferred method is WordPress Font Library to allow access to Google Fonts so WP Core will handle the download and enqueue.

Head to Appearance > Fonts and click Install Fonts where you need to first Allow access to Google Fonts.

Then simply search for the fonts you want to install and they will be installed to wp-content/uploads/fonts/ which are now available to call using var(--wp--preset--font-family--[font_name_here]) like this:

theme.json

"styles": {
    "typography": {
      "fontFamily": "var(--wp--preset--font-family--inter)",
      "lineHeight": "1.6",
      "fontSize": "1.1rem"
    },

That it, its that simple but if we want a one file change method, we can simply call the fonts externally using the next method.

---

Method 2: Loading Fonts Externally

If we’re looking for a quick and dirty method for development, we can handle everything within the theme.json by adding the “src”: directly in the “fontFace”: [ object like this: "src": [ "https://fonts.gstatic.com/s/roboto/v30/KFOmCnqEu92Fr1Mu4mxK.woff2" ]

Here is a quick, reference-ready guide on how to add or update custom web fonts using theme.json. You can look back at this whenever you need to add a new font or update weights in the future.

The 3-Step Font Blueprint for theme.json

Step 1: Register the Font (Declare Assets)

Find the settings.typography.fontFamilies array. This is where you declare the font family name, its slug (which creates the CSS variable), and the actual files (fontFace).

Rule of Thumb: Google Fonts splits weights across different files. Always create a separate object inside fontFace for each weight you need.

JSON

"fontFamilies": [
  {
    "fontFamily": "\"Roboto\", sans-serif",
    "slug": "roboto",
    "name": "Roboto",
    "fontFace": [
      {
        "fontFamily": "Roboto",
        "fontWeight": "400",
        "fontStyle": "normal",
        "fontDisplay": "fallback",
        "src": [ "https://fonts.gstatic.com/s/roboto/v30/KFOmCnqEu92Fr1Mu4mxK.woff2" ]
      },
      {
        "fontFamily": "Roboto",
        "fontWeight": "700",
        "fontStyle": "normal",
        "fontDisplay": "fallback",
        "src": [ "https://fonts.gstatic.com/s/roboto/v30/KFOlCnqEu92Fr1MmWUlfBBc4.woff2" ]
      }
    ]
  }
]

Step 2: Apply Globally to Body Text

Scroll down to the "styles" object. Target "typography" directly underneath it to set your global fallback font using your new slug variable: var(--wp--preset--font-family--[YOUR-SLUG]).

JSON

"styles": {
  "typography": {
    "fontFamily": "var(--wp--preset--font-family--roboto)"
  }
}

Step 3: Apply to Specific Elements (Headings, Links, etc.)

To explicitly style blocks or elements like headings, look inside styles.elements. Add the exact same variable target and ensure your "fontWeight" matches one of the asset weights you registered in Step 1.

JSON

"elements": {
  "heading": {
    "typography": {
      "fontFamily": "var(--wp--preset--font-family--roboto)",
      "fontWeight": "700"
    }
  }
}

🛠️ The Troubleshooting Checklist

If you update theme.json and the fonts don’t change on your screen, run through these checks:

1. The CORS Block / Font-Face Failure (Error Code: status=2147746065)

• The Issue: The browser console displays a downloadable font: download failed message accompanied by status code 2147746065. On-screen, your custom typography reverts to system defaults like Arial or Times New Roman.
• Why it happens: This is a security block. Google’s static servers (fonts.gstatic.com) strictly guard direct binary hotlinking and often deny access to your local development environment ([http://127.0.0.1](http://127.0.0.1)).
• Why Roboto worked but others broke: Google frequently shifts and rotates their link hashes. The specific hash used in the Roboto example remains unblocked or cached, whereas newly scraped direct static links for other fonts immediately run into CORS restriction walls.
• The Dev Fix: Bypass Google’s network restrictions by sourcing your development files from an open CORS delivery network like jsDelivr/Fontsource. Update the "src" attribute in your JSON mapping to use a version-locked open package link instead:JSON"src": [ "https://cdn.jsdelivr.net/npm/@fontsource/montserrat@5.0.0/files/montserrat-latin-700-normal.woff2" ]
• The Prod Fix: Download the physical .woff2 files into your theme folder under assets/fonts/ and link to them using "file:./assets/fonts/filename.woff2". This eliminates external server dependencies completely.

2. Clear the WordPress Object Cache

WordPress aggressively caches `theme.json` outputs to optimize execution times. Always flush your site/server cache, or transient entries in your local database, immediately after saving edits to this configuration file.

3. Check for Site Editor Overrides

If an administrator has modified or saved custom typography selections via the Site Editor user interface (Appearance > Editor > Styles > Typography), WordPress writes those explicit styling choices straight to the database.

Database records take precedence and will completely override whatever strings or changes you push to your local theme.json template. Simply access the typography settings in the user interface and reset them to defaults to restore your file’s administrative control.