New Feature: Font Library

Introduced in WordPress 6.5, the Font Library allows users to manage fonts directly in the editor. It comes with a set of APIs that allow developers to control, adapt, and disable its behavior.

Font Collections

A Font Collection is a list of font family definitions that can be installed by the user via the editor. The font family definition is a fontFamily item in theme.json format. By default, WordPress 6.5 allows users to opt-in to a collection listing for Google Fonts. To allow sites to remain GDPR compliant, installing a Google Font downloads the file to the WordPress server.

When a Font Collection is registered, it will appear in the Font Library UIUI User interface in the editor. From here, users can install and activate fonts from the collection.

Adding a Font Collection

A new Font Collection can be added using the wp_register_font_collection() function. This can be done by supplying a list of font families and their font faces in either PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher or JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. format as part of the Font Collection array.

Here is an example of adding a Font Collection in PHP:

$font_families = [
	array(
		'font_family_settings' => (
			array (
				'fontFamily' => 'Open Sans, sans-serif',
				'slug'       => 'open-sans',
				'name'       => 'Open Sans',
				'fontFace'   => array (
					array (
							'fontFamily' => 'Open Sans',
							'fontStyle'  => 'normal',
							'fontWeight' => '300',
							'src'        => 'https://fonts.gstatic.com/s/opensans/v40/memSYaGs126MiZpBA-UvWbX2vVnXBbObj2OVZyOOSr4dVJWUgsiH0C4iY1M2xLER.woff2',
					),
					array (
							'fontFamily' => 'Open Sans',
							'fontStyle'  => 'italic',
							'fontWeight' => '400',
							'src'        => 'https://fonts.gstatic.com/s/opensans/v40/memQYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWq8tWZ0Pw86hd0Rk8ZkaVIUwaERZjA.woff2'
					),
				),
			)
		),
		'categories' => [ 'sans-serif' ],
	),
	array(
		'font_family_settings' => (
			array (
				'fontFamily' => 'Monoton, system-ui',
				'slug'       => 'monoton',
				'name'       => 'Monoton',
				'fontFace'   => array (
					array (
							'fontFamily' => 'Monoton',
							'fontStyle'  => 'normal',
							'fontWeight' => '400',
							'src'        => 'https://fonts.gstatic.com/s/monoton/v19/5h1aiZUrOngCibe4fkPBQ2S7FU8.woff2',
							'preview'    => 'https://s.w.org/images/fonts/17.7/previews/monoton/monoton-400-normal.svg'
					),
				),
			)
		),
		'categories' => [ 'display' ],
	),
	array(
		'font_family_settings' => (
			array (
				'fontFamily' => 'Arial, Helvetica, Tahoma, Geneva, sans-serif',
				'slug'       => 'arial',
				'name'       => 'Arial',
			)
		),
		'categories' => [ 'sans-serif' ],
	),
];
	
$categories = [
	array(
	'name' => _x( 'Display', 'Font category name' ),
		'slug' => 'display',
	),
	array(
		'name' => _x( 'Sans Serif', 'Font category name' ),
		'slug' => 'sans-serif',
	),
];

$config = array (
	'name'          => _x( 'My font collection', 'Font collection name' ),
	'description'   => _x(  'A collection of my favorite fonts.', 'Font collection description' ),
	'font_families' => $font_families,
	'categories'    => $categories,
);

wp_register_font_collection ( 'my-font-collection', $config );

Please note that the name and description fields of the Font Collection array must be translatable, which can be achieved by wrapping the strings in the _x() function. Font Family names are not typically translated. For more information and background discussion, see #60509.

JSON format for the font_families field can be a local path or a remote URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org that points to the JSON file.

Removing a Font Collection

A Font Collection can be disabled by using the wp_unregister_font_collection() function. Here is an example which disables the default font collection:

add_action( 'init', function() {
	wp_unregister_font_collection( 'default-font-collection' );
} );

For more information, see #57980.

Installing and Activating Fonts

Fonts definitions are based on the theme.json format for font settings. “Installing” a font to the site saves the theme.json formatted settings from the collection into the database, so the font can be activated for any theme.

When the font is “activated,” the Global Styles settings for the theme are updated so that the font is included, along with the fonts defined by the theme, and can be used in the typography settings for Global Styles and individual blocks.

When switching to a new theme, installed fonts need to be re-activated, to update the site’s Global Styles settings for that theme. If Global Styles for a theme are reset, this will deactivate all installed fonts, but they will remain installed on the site and can be reactivated as desired.

Additionally, the Font Library can be used to deactivate fonts included with the theme, if they aren’t needed, to improve the loading performance of the site.

Customizing the Fonts Upload Directory

By default, fonts will be uploaded to the wp-content/fonts directory. However, this location can be customized as required using the font_dir filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output.. For installations that don’t support modification of the wp-content directory, it is recommended to install the Fonts To Uploads plugin or use the code snippet below.

It is possible to return the location of the fonts upload directory by using wp_get_font_dir().

The example below changes the fonts directory to the WordPress “Uploads” directory (by default, this is wp-content/uploads):

function alter_wp_fonts_dir( $defaults ) {
	$wp_upload_dir = wp_get_upload_dir();
	$uploads_basedir = $wp_upload_dir['basedir'];
	$uploads_baseurl = $wp_upload_dir['baseurl'];

	$fonts_dir = $uploads_basedir . '/fonts';
	// Generate the URL for the fonts directory from the font dir.
	$fonts_url = str_replace( $uploads_basedir, $uploads_baseurl, $fonts_dir );

	$defaults['path'] = $fonts_dir;
	$defaults['url']  = $fonts_url;

	return $defaults;
}
add_filter( 'font_dir', 'alter_wp_fonts_dir' );

When modifying the upload location, it is important to ensure that the chosen location exists and has appropriate read/write permissions set.

Like the wp-content/uploads directory, the fonts upload directory will not adhere to wp_is_file_mod_allowed / DISALLOW_FILE_MODS to prevent font uploads.

For further info, see #59417 and this post.

How to Disable the Font Library

The Font Library is accessible via the editor by default.

Disable the UI

The UI can be disabled using a filter to customize the editor settings:

function disable_font_library_ui( $editor_settings ) { 
   	 $editor_settings['fontLibraryEnabled'] = false;
   	 return $editor_settings; 
}

add_filter( 'block_editor_settings_all', 'disable_font_library_ui' );

Disable the REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/.

The register_post_type_args() filter can be used to disable the wp_font_family and wp_font_face REST API endpoints:

function my_disable_fonts_rest_api_endpoints( $arg, $post_type ) {
	if ( 'wp_font_family' === $post_type || 'wp_font_face' === $post_type ) {
		$arg['show_in_rest'] = false;
	}

	return $arg;
}
add_filter( 'register_post_type_args', 'my_disable_fonts_rest_api_endpoints', 10, 2 );

The rest_endpoints filter can be used to disable the font collections APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. endpoints:

function my_disable_font_collections_rest_api_endpoints( $endpoints ) {
	foreach ( $endpoints as $route => $endpoint ){
		if ( str_starts_with( $route, '/wp/v2/font-collections' ) ) {
			unset( $endpoints[ $route ] );
		}
	}

	return $endpoints;
}
add_filter( 'rest_endpoints', 'my_disable_font_collections_rest_api_endpoints' );

WordPress includes a polyfill for str_starts_with(), so it is safe to run this function in the above code on < PHP 8.0.

This allows extenders to disable the Font Library, while retaining the UI for managing fonts provided by the active theme.

For more info, see #55275 and #57818.

New REST API

The Font Library feature introduces three new REST API endpoints:

• wp/v2/font-collections – endpoint for predefined lists (i.e. “collections”) of font families.
• wp/v2/font-families – endpoint for parent font family which typically (but not always) contains one or more font faces (i.e. the individual fonts).
• wp/v2/font-families/<id>/font-faces – endpoint for individual font faces within a family.

For detailed documentation about each of the new endpoints, please refer to the REST API Handbook and #57616.

Props and a massive thank you to everyone who helped put this dev notedev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include a description of the change, the decision that led to this change, and a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase. together: @mmaattiiaass, @grantmkin, @peterwilsoncc, @youknowriad, @get_dave, @stevenlinx, @leonnugraha.

Update: This dev-note has been modified following a late decision to modify how font files were stored. Please refer to this follow up post on the subject of font file storage.

Update: This dev-note has been modified to update the code examples in the “Disable the REST API” section, as the previous example included the use of unregister_post_type(), which does not work on built-in post types. Please update any references to the previous example.

#6-5, #dev-notes, #dev-notes-6-5