Filters for theme.json data

WordPress 6.1 has introduced some server-side filters to hook into the theme.json data provided at the different data layers:

  • wp_theme_json_data_default: hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. into the default data provided by WordPress
  • wp_theme_json_data_blocks: hooks into the data provided by the blocks
  • wp_theme_json_data_theme: hooks into the data provided by the theme
  • wp_theme_json_data_user: hooks into the data provided by the user

Each 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. receives an instance of the WP_Theme_JSON_Data class with the data for the respective layer. To provide new data, the filter callback needs to use the update_with( $new_data ) method, where $new_data is a valid theme.json-like structure.

As with any theme.json, the new data needs to declare which version of the theme.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. is using, so it can correctly be migrated to the runtime one if it’s different.

Example: add a new color palette

For example, this is how to pass a new color palette for the theme and disable the text color UIUI User interface:

function filter_theme_json_theme( $theme_json ){
	$new_data = array(
		'version'  => 2,
		'settings' => array(
			'color' => array(
				'text'       => false,
				'palette'    => array( /* New palette */
					array(
						'slug'  => 'base',
						'color' => 'white',
						'name'  => __( 'Base', 'theme-domain' ),
					),
					array(
						'slug'  => 'contrast',
						'color' => 'black',
						'name'  => __( 'Contrast', 'theme-domain' ),
					),
				),
			),
		),
	);

	return $theme_json->update_with( $new_data );
}
add_filter( 'wp_theme_json_data_theme', 'filter_theme_json_theme' );

By declaring what data they want to override, 3rd parties have more control without having to worry about migrating their code when or if there’s an update to the theme.json shape. By using this mechanism as suggested, coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. will always make sure their data gets migrated to the latest.

Take a look at the how-to guide for theme.json and the specification.

Props to @bph and @webcommsat for review.

#6-1, #dev-notes, #dev-notes-6-1