Framework for managing web fonts, font faces, and font collections in WordPress.

Since: 6.4.0 (core), 6.5.0 (Font Library/Collections)
Source: wp-includes/fonts.php, wp-includes/fonts/

Components

Architecture

The Fonts API has two main subsystems:

1. Font Face Generation (6.4.0+)

Handles outputting @font-face CSS rules for fonts defined in theme.json:

theme.json
    └── WP_Font_Face_Resolver::get_fonts_from_theme_json()
            └── WP_Font_Face::generate_and_print()
                    └── <style class="wp-fonts-local">@font-face{...}</style>

2. Font Library (6.5.0+)

Manages font collections (like Google Fonts) that users can install:

wp_register_font_collection()
    └── WP_Font_Library::register_font_collection()
            └── new WP_Font_Collection()

WP_Font_Collection::get_data()
    └── load_from_json() (file or URL)
            └── Sanitize and cache font families

Font Face Properties

Supported CSS @font-face properties:

Font Display Values

Font File Formats

Source ordering (browser optimization):

1. woff2 – Best compression, modern browsers
2. woff – Good compression, wide support
3. ttf/truetype – Uncompressed, universal
4. eot – Legacy IE
5. otf/opentype – OpenType format

Font Directory

Uploaded fonts are stored in wp-content/uploads/fonts/:

$font_dir = wp_get_font_dir();
// [
//     'path'    => '/var/www/html/wp-content/uploads/fonts',
//     'url'     => 'https://example.com/wp-content/uploads/fonts',
//     'subdir'  => '',
//     'basedir' => '/var/www/html/wp-content/uploads/fonts',
//     'baseurl' => 'https://example.com/wp-content/uploads/fonts',
//     'error'   => false,
// ]

Post Types

Fonts are stored as custom post types:

Default Collections

WordPress registers the Google Fonts collection by default:

wp_register_font_collection( 'google-fonts', [
    'name'          => 'Google Fonts',
    'description'   => 'Install from Google Fonts...',
    'font_families' => 'https://s.w.org/images/fonts/.../google-fonts-with-preview.json',
    'categories'    => [ 'Sans Serif', 'Display', 'Serif', 'Handwriting', 'Monospace' ],
]);

theme.json Integration

Define fonts in theme.json:

{
  "settings": {
    "typography": {
      "fontFamilies": [
        {
          "fontFamily": "Inter, sans-serif",
          "slug": "inter",
          "name": "Inter",
          "fontFace": [
            {
              "fontFamily": "Inter",
              "fontWeight": "400",
              "fontStyle": "normal",
              "src": [ "file:./assets/fonts/inter-regular.woff2" ]
            },
            {
              "fontFamily": "Inter",
              "fontWeight": "700",
              "fontStyle": "normal",
              "src": [ "file:./assets/fonts/inter-bold.woff2" ]
            }
          ]
        }
      ]
    }
  }
}

The file:./ prefix is replaced with the theme’s URL.