Reference Styles values in theme.json

With WordPress 6.1, theme developers can style elements with references from other settings.

Theme designs often require consistency in the styles applied to blocks. This can be achieved by setting Styles properties which are inherited by blocks using the inheritance of the CSSCSS Cascading Style Sheets. cascade. In some cases blocks want to apply settings from Styles to a different property of the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. – for example the button element might want to use the global text color for its background color and the global background for its text color.

To solve this problem, themes need to be able to share Styles settings with blocks. This will make it easier for users to update these shared properties across all their blocks. Again, as example for button element the developer wants to use the text color for its background. If the button element is set up as in the example above, then when a user edits the global text color, the background color of their buttons will also be updated, too.

To achieve this, a new ref property was added to 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. which allows one property to set itself to the value of another, for example defining this for button elements:

"elements": {
	"button": {
		"color": {
			"background": {
				"ref": "styles.color.text"
			"text": {
				"ref": "styles.color.background"

Styles will convert {ref: "styles.color.background"} the value at: styles > color > background in theme.json.


It is currently only possible to use ref to get one value from theme.json; a ref value cannot point to another ref. This also prevents circular refs from causing problems.

Props to @bph and @webcommsat for review of this post.

#6-1, #dev-notes, #dev-notes-6-1, #styles, #themes