Full Site Editing

Estimated reading time: 3 minutes

What are theme.json elements?

Sometimes you want to style a part of a complex block, and you want more control over the block styles than just adding the same colors or font sizes to all the inner elements.
Let’s take these examples:

• When you style the heading block using styles.blocks.heading, the styles are applied to all heading levels.
• If you style the button block, WordPress does not apply the styles to HTML buttons like submit buttons, and you end up having to style these separately.

This is where the theme.json elements category becomes useful. The Gutenberg developers introduced elements to theme.json to solve the examples above. It also lets you style links and captions on the website and inside blocks.
Block developers can use the new class names in their custom blocks to make it easier for themes to style inner elements.

It is important to know that theme.json elements are not strictly HTML elements. WordPress only supports a few selected elements, and applies some styles to a class name rather than the HTML tag.

Which elements can I use with theme.json?

Element	CSS selector	Supported by
link	a	WordPress 6.0
	:link and :any-link	WordPress 6.2
h1 to h6	Individual h1, h2, h3, h4, h5, h6	WordPress 6.0
heading	All headings at once: h1, h2, h3, h4, h5, h6	WordPress 6.1
button	.wp-element-button and .wp-block-button__link	WordPress 6.1
caption	.wp-element-caption, .wp-block-audio figcaption, .wp-block-embed figcaption, .wp-block-gallery figcaption, .wp-block-image figcaption, .wp-block-table figcaption, .wp-block-video figcaption	WordPress 6.1
cite	cite	WordPress 6.1
form elements	Planning stages, see #34198

Examples

Elements are used in the styles section of theme.json and in styles.blocks.blockname.

Headings

Here is how you would add a default font weight to all headings, and add a font family to all H2 headings, regardless of if they are a heading block or not.
Below that, I am styling the comment reply heading inside the comments form block:

{
	"version": 2,
	"styles": {
		"elements": {
			"heading": {
				"typography": {
					"fontWeight": "700"
				}
			},
			"h2": {
				"typography": {
					"fontFamily": "var(--wp--preset--font-family--source-serif-pro)"
				}
			}
		},
		"blocks": {
			"core/post-comments-form": {
				"elements": {
					"h3": {
						"typography": {
							"textTransform": "uppercase"
						}
					}
				}
			}
		}
	}
}

The CSS that is applied to the comment reply heading is:

.editor-styles-wrapper .wp-block-post-comments-form h3 {
    text-transform: uppercase;
}
.editor-styles-wrapper h1, .editor-styles-wrapper h2, .editor-styles-wrapper h3, .editor-styles-wrapper h4, .editor-styles-wrapper h5, .editor-styles-wrapper h6 {
    font-weight: 700;
}

The block does not use the font family since it is an H3, not an H2.

Button

You can use elements.button to style most buttons with the same styles. The exception is the navigation block buttons.
The style settings you add to elements.button are applied to the .wp-element-button CSS class. The following blocks uses the class: Button, file, search, and post comments form.

In the following theme.json example I am adding default styles for all buttons, and then reducing the font size for the button in the file block:

{
	"version": 2,
	"styles": {
		"elements": {
			"button": {
				"typography": {
					"fontWeight": "700",
					"fontSize": "1.2rem"
				},
				"color": {
					"background": "#fafafa",
					"text": "#111111"
				},
				"border": {
					"radius": "0",
					"width": "2px",
					"style": "solid"
				}
			}
		},
		"blocks": {
			"core/file": {
				"elements": {
					"button": {
						"typography": {
							"fontSize": ".8rem"
						}
					}
				}
			}
		}
	}
}

Caption

You can use elements.caption to style fig captions used for several blocks with the figure element: Galleries, images, table, video, audio, and embeds.

{
	"version": 2,
	"styles": {
		"elements": {
			"caption": {
				"color": {
					"text": "#111111"
				},
				"typography": {
					"fontSize": "0.8rem",
					"lineHeight": ".7",
					"textTransform": "uppercase"
				}
			}
		}
	}
}

Cite

With elements.cite you can add default styles to the citation in the quote block:

{
	"version": 2,
	"styles": {
		"elements": {
			"cite": {
				"color": {
					"text": "#333"
				},
				"typography": {
					"fontSize": "0.8rem",
					"lineHeight": ".7"
				}
			}
		}
	}	
}

Resources

Moving Core block styling to JSON