Document how to include to a 3rd party typeface in global styles

[skorasaurus]

Description

Not sure where in the documentation it would go; but fellow users would benefit to have documentation how to include a 3rd party typeface (one that is not local to a user's device) into Global Styles/theme.json

I figured how to load a font that is locally hosted and included in my theme:

Global Styles reads the value from a @font-face selector in the theme's CSS.

(Example scenario, the font is in the theme's folder fonts)

@font-face {
  font-family: 'CustomNameOfMyFontFamily';
  src: url('fonts/path-to-my-font.woff2') format("woff2"), url('fonts/path-to-my-font.woff2') format("woff");
}

Then in the theme.json file, fontFamily property needs to match the value of font-family's property in the CSS declaration.

the slug value is a custom string - that you can choose the name of (I choose 'custom-slug' in the example below) and it'll available will be a CSS variable and its name will follow the structure specified in https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/#presets

--wp--preset--font-family--custom-slug

For example, with the declaration above in css;

"typography": {
      "fontFamilies": [
        {
          "fontFamily": "CustomNameOfMyFontFamily",
          "slug": "custom-slug",
          "name": "Work Sans"
        },
        {
        "fontFamily": "Poppins",
        "name": "Poppin fresh!",
        "slug": "poppins"
          }
}

For a remote font, something like following in a css file

  @font-face {
    font-family: 'Poppins';
    font-style: normal;
    font-weight: 400;
    font-display: swap;
    src: url(https://fonts.gstatic.com/s/poppins/v20/pxiEyp8kv8JHgFVrJJfecnFHGPc.woff2) format('woff2');
    unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
  }

Semi-related:

I don't know what best practices have been documented anywhere for loading 3rdparty fonts into WordPress

For Google, I found https://github.com/Automattic/themes/blob/1aa5058bcff44951877c2db4f461fd4a46433613/blockbase/functions.php#L75

That is then read in a blockbase child theme https://github.com/Automattic/themes/blob/1aa5058bcff44951877c2db4f461fd4a46433613/quadrat/theme.json#L390

[richtabor]

For Google, I found https://github.com/Automattic/themes/blob/1aa5058bcff44951877c2db4f461fd4a46433613/blockbase/functions.php#L75

I wonder if this could be useful as a core function. I suspect every theme using a Google font will copy/paste this.

[karmatosed]

I think it would make a great core function so +1 to having it rolled in or a least documented.

[mtias]

Note there's some ongoing work to make font assets more recognizable across WordPress: WordPress/wordpress-develop#1573

[aristath]

The patch on WordPress/wordpress-develop#1573 adds some generic functions like wp_enqueue_webfont etc. Once that one gets merged we can start implementing things for theme.json and allow adding webfonts from a 3rd-party API - or even from locally-hosted/embedded webfonts 👍

[ryanwelcher]

Is this issue still relevant?

[skorasaurus]

I think so.

Coming from someone who wants to change the font (which I'd distribute with the theme) to a block theme that I found:

I first checked: https://wordpress.org/search/font/

• leads to https://wordpress.org/documentation/article/typography-settings-overview/
• doesn't mention how to add it (not sure if it's supposed to)

Then, I decided to try what I did in first comment (I updated it to add instructions for a 3rd party font) and that successfully load a couple 3rd-party fonts into the site editor.

(again, I didn't test this very much but the fonts are available at wp-admin/site-editor.php?canvas=edit and if I select them in the typography sidebar panel at that page, they immediately load in the site editor.

However,
https://core.trac.wordpress.org/ticket/46370 is not yet completed (which I am assuming is the canonical, recommend way to load 3rd party fonts going forward);

I'd defer to you whether you want to wait until that's including Gutenberg to close this; or to just document what I did above as a stop-gap.

[justintadlock]

The docs in the Theme Handbook should cover this: https://developer.wordpress.org/themes/global-settings-and-styles/settings/typography/#registering-web-fonts-font-faces

Does this cover everything you're asking for @skorasaurus? If not, I'd recommend opening a ticket in the Documentation repository (with the themes label) for updates to that doc: https://github.com/WordPress/Documentation-Issue-Tracker/issues

[skorasaurus]

Thanks @justintadlock ; thanks for the heads up: I was able to get a custom font up and running in less than 10 minutes with the docs.