How to add Google fonts to WordPress themes

When enqueuing Google fonts, there are five things to consider:

1. Is the font enqueued instead of included directly in the template files or CSS?
2. Is the font enqueued on the correct hook?
3. Is the font URL protocol independent?
4. Can translators deactivate the font if their language’s character set isn’t supported?
5. Can the font be dequeued by child themes?

In this post, we’ll go over the best practices for enqueuing Google fonts in your WordPress theme.

Introducing the Font URLs function

Instead of hardcoding URLs to Google font resources, we will write a function to take care of all the logic related to these fonts. Let’s start out with the basic outline of the function. It takes no parameters and returns a string, which starts out empty.

function theme_slug_fonts_url() {
$fonts_url = '';

return $fonts_url;
}

Now we’ll add two fonts: Lora and Open Sans.

/* Translators: If there are characters in your language that are not
* supported by Lora, translate this to 'off'. Do not translate
* into your own language.
*/
$lora = _x( 'on', 'Lora font: on or off', 'theme-slug' );

/* Translators: If there are characters in your language that are not
* supported by Open Sans, translate this to 'off'. Do not translate
* into your own language.
*/
$open_sans = _x( 'on', 'Open Sans font: on or off', 'theme-slug' );

We use the WordPress _x() translation function to make the text “on” available for translation, while adding context via the second parameter. We also added a PHP comment to give further instructions to the translators in code.

As we use a translation function, the text above will show up in translation tools like GlotPress. If translators want to enable the font, they translate “on” as “on”. If they want to disable it, they translate it to “off”.

This may seem weird, but it’s an effective way to allow international users to keep their website from breaking. With that done, we can construct the correct URL depending on what fonts are enabled.

if ( 'off' !== $lora || 'off' !== $open_sans ) {
$font_families = array();

if ( 'off' !== $lora ) {
$font_families[] = 'Lora:400,700,400italic';
}

if ( 'off' !== $open_sans ) {
$font_families[] = 'Open Sans:700italic,400,800,600';
}
}

First, we check to see if both fonts have been deactivated by the translators; no need to continue in that case. Then we add the font names and styles to an array. The numbers after the colon represent different font styles—weights, cursive variants, small caps, etc.

It’s important that you only load the font styles you need to ensure that the loading time is as short as possible.

Now that we have this data, we can generate the fonts URL. The following code should be placed into the if statement above.

$query_args = array(
'family' => urlencode( implode( '|', $font_families ) ),
'subset' => urlencode( 'latin,latin-ext' ),
);

This code combines the array of font families into a single string, separated with the | (pipe) symbol. It also adds the subset parameter that determines which character sets to use. As with the weights, only load the character sets you need.

The PHP function urlencode() ensures that the data we pass to it gets encoded correctly to be used as a query part in a URL. The final step is appending this data to the URL to Google’s font servers.

$fonts_url = add_query_arg( $query_args, 'https://fonts.googleapis.com/css' );

Here we use the add_query_arg() function to build the URL. The complete function looks like this:

function theme_slug_fonts_url() {
$fonts_url = '';

/* Translators: If there are characters in your language that are not
* supported by Lora, translate this to 'off'. Do not translate
* into your own language.
*/
$lora = _x( 'on', 'Lora font: on or off', 'theme-slug' );

/* Translators: If there are characters in your language that are not
* supported by Open Sans, translate this to 'off'. Do not translate
* into your own language.
*/
$open_sans = _x( 'on', 'Open Sans font: on or off', 'theme-slug' );

if ( 'off' !== $lora || 'off' !== $open_sans ) {
$font_families = array();

if ( 'off' !== $lora ) {
$font_families[] = 'Lora:400,700,400italic';
}

if ( 'off' !== $open_sans ) {
$font_families[] = 'Open Sans:700italic,400,800,600';
}

$query_args = array(
'family' => urlencode( implode( '|', $font_families ) ),
'subset' => urlencode( 'latin,latin-ext' ),
);

$fonts_url = add_query_arg( $query_args, 'https://fonts.googleapis.com/css' );
}

return esc_url_raw( $fonts_url );
}

And this is the encoded URL string that is returned:

https://fonts.googleapis.com/css?family=Lora%3A400%2C700%2C400italic%7COpen+Sans%3A700italic%2C400%2C800%2C600&subset=latin%2Clatin-ext

With this function complete, we can enqueue our fonts.

Enqueuing on the front end

Enqueuing the font on the front end for your visitors is straightforward:

function theme_slug_scripts_styles() {
wp_enqueue_style( 'theme-slug-fonts', theme_slug_fonts_url(), array(), null );
}
add_action( 'wp_enqueue_scripts', 'theme_slug_scripts_styles' );

Our fonts are included with a unique handle prefixed with the theme slug, with no dependencies declared and no version number indicated. This allows the fonts to be dequeued by a child theme, either using the handle with wp_dequeue_style(), or by removing the entire function from the hook with remove_action(). Note the wp_enqueue_scripts action, which is the correct hook for adding stylesheets and scripts to your theme.

Adding Google fonts to the editor

If your theme uses editor styles, you need to enqueue the fonts on the back end as well. You can do this using the add_editor_style() function. It accepts an array of stylesheets to enqueue, and you can pass your font URL function as one of them:

function theme_slug_editor_styles() {
add_editor_style( array( 'editor-style.css', theme_slug_fonts_url() ) );
}
add_action( 'after_setup_theme', 'theme_slug_editor_styles' );

Note that the correct hook is after_setup_theme this time.

Adding fonts to the Custom Header screen

The legacy way to customize a theme’s header image is done via the Appearance → Header screen. To ensure the preview is displayed correctly in the admin, you need to include the Google fonts like so:

function theme_slug_custom_header_fonts() {
wp_enqueue_style( 'theme-slug-fonts', theme_slug_fonts_url(), array(), null );
}
add_action( 'admin_print_styles-appearance_page_custom-header', 'theme_slug_custom_header_fonts' );

Using the admin_print_styles-appearance_page_custom-header action, we can ensure that the fonts only get loaded on this particular screen and not on every admin page load.

That’s it!

If you have any questions, let us know!