Plugin and theme developers have been able to enqueue scripts and styles for years, but fonts have always been more complicated to enqueue. Following ticket #46370 and last September’s proposal to add a fonts enqueue API in WordPress Core, we now have a patch ready.
With the recent advancements in Gutenberg, global-styles, and an effort to consolidate options and UIs in the site-editor, a Webfonts API is becoming a necessity as it will allow theme developers to define fonts in their theme.json files.
In this first iteration, we are mirroring the scripts & styles enqueueing functions for consistency. Since enqueueing a webfont entails enqueuing a stylesheet (or adding inline styles) to enqueue the font files themselves, the webfonts API functions act as wrappers for the stylesheets API (with the appropriate modifications where needed).
The intention for this initial iteration is to provide a basis we can build upon and improve in the future – which is why it was kept minimal. More improvements and functionality will be added in the future, but in order to improve it, it has to be there.
The patch adds the following functions:
wp_register_webfontwp_deregister_webfontwp_enqueue_webfontwp_dequeue_webfontwp_webfont_iswp_webfont_add_data
The syntax of all these functions is identical to their style counterparts, so wp_register_webfont is the same as wp_register_style and so on. The only difference is the use of $params in lieu of $deps for practical reasons.
Notes:
- The styles registered for webfonts automatically get a
webfont- prefix to avoid conflicts with any similarly named stylesheets. This provides a clear distinction between normal styles and webfonts styles, while keeping the implementation simple. - Since webfonts don’t have dependencies, the
$deps argument was replaced with $params. These params can be used to register a webfont from local files, and auto-generate the CSS for @font-face.
Enqueuing a webfont from a remote URL
To use a webfonts API (Google Fonts, Adobe fonts, etc), we can use the URL provided by the API directly:
1 2 3 4 5 6 7 8 | add_action( 'wp_enqueue_scripts', function() {
wp_enqueue_webfont(
'dancing-script',
'http://wayback.fauppsala.se:80/wayback/20211007172233/https://fonts.googleapis.com/css2?family=Dancing+Script:wght@500;600&display=swap',
);
} );
|
This is identical to what we would previously do using the wp_enqueue_style function, but now using a more appropriately named wp_enqueue_webfont function. With the example code above, the webfont will be enqueued and the stylesheet’s handle will be webfont-dancing-script.
Generating CSS for a webfont
It is possible to generate the CSS for a webfont using the provider parameter and the wp_webfont_generate_styles function.
A provider is an object with details about the provider’s implementation and a method to get (or generate) the CSS from that API.
Generating styles for bundled font files
To generate styles for bundled font-files, set the provider to new WP_Fonts_Provider_Local().
1 2 3 4 5 6 7 8 9 10 11 | $my_font_styles = wp_webfont_generate_styles( array(
'provider' => new WP_Fonts_Provider_Local(),
'font-family' => 'My Font',
'font-display' => 'swap',
'font-style' => 'normal',
'font-weight' => '400',
'src' => array(
get_template_directory_uri() . '/fonts/font.woff2',
get_template_directory_uri() . '/fonts/font.woff',
),
) );
|
Generating styles for Google fonts
To generate styles for a Google font, set the provider to new WP_Fonts_Provider_Google.
1 2 3 4 5 | $roboto_styles = wp_webfont_generate_styles( array(
'provider' => new WP_Fonts_Provider_Google(),
'font-family' => 'Roboto',
'font-weight' => '400',
) );
|
Using the generated styles
You can attach the styles to an existing stylesheet using wp_add_inline_style:
1 2 3 4 5 6 7 8 9 10 11 12 | add_action( 'wp_enqueue_scripts', function() {
wp_enqueue_style( 'my-theme-styles', get_theme_file_uri( 'style.css' ) );
$roboto_styles = wp_webfont_generate_styles( array(
'provider' => new WP_Fonts_Provider_Local(),
'font-family' => 'Roboto',
'font-weight' => '400',
) );
wp_add_inline_style( 'my-theme-styles', $roboto_styles );
} );
|
Alternatively, you can use the wp_enqueue_webfont function:
1 2 3 4 5 6 7 | add_action( 'wp_enqueue_scripts', function() {
wp_enqueue_webfont( 'roboto-400', '', array(
'provider' => new WP_Fonts_Provider_Local(),
'font-family' => 'Roboto',
'font-weight' => '400',
) );
} );
|
This will internally call wp_enqueue_style with a blank $src, and attach the webfoot styles to the defined $handle.
Adding implementations for more 3rd-party APIs
At the moment of this writing, Google-Fonts is the most popular API for web fonts, and the only one publicly available, free, with OpenSource-compatible fonts.
Adding implementations for more APIs in the future can be done by extending the WP_Fonts_Provider class.
The $params argument
The $params argument is formatted as an array and accepts all valid CSS props of @font-face as its array keys. Any extra args are ignored. The list of valid descriptors was taken from MDN.
Defining a font-family is mandatory, and skipping that results in no CSS getting generated.
The src
If we’re enqueueing a webfoot from bundled files, then we can use the src to define the files. If we only want to define a single file for the webfont, then we can add it as a string ('src' => $url).
If we have multiple files for the webfont (different formats to support older browsers), then we can use an array ('src' => [ $url1, $url2 ]). In this case, the URLs get internally reordered for browser support (woff2, woff, ttf, eot, otf). SVG for webfonts is not supported because they have been deprecated (see caniuse.com/svg-fonts), so if provided it gets removed (like any other invalid type).
Note: The src can also accept data-urls.
Variable fonts
The font-variation-settings property accepts either a string (normal), or an array of key/value pairs (e.g. ["wght" => 637, "wdth" => 100]) and returns a string of these values (e.g., wght 637, wdth 100).
Props @jonoaldersonwp, @sergeybiryukov for reviewing
This is great, I see the ability to lock blocks in particular as a game changer!
Under “Performance Benchmark” do the Gutenberg versions need to be edited from `10.x` to `11.x` or are the most current metrics from Gutenberg `10.x`?
Indeed! Sorry about that 🙂 – I updated them.