The introduction of the theme.json file, commonly referred to as the Global Styles and Global Settings APIs, arrived in WordPress 5.8. This feature enables theme developers to configure site-wide styles, block settings, and block styles from a centralized location, reducing the need for CSS in many cases (though not always). Version two of theme.json added a new feature to enable developers to define CSS custom properties through custom presets. As a quick refresher, custom properties are created to be reused like variables but are set with a custom syntax starting with two dashes (e.g., --line-height-xs: 1
) while the presets we are discussing are written in json and then generated into custom properties. With these presets, theme developers can create consistent styles for blocks and block variations by using custom properties for any number of use cases. These potential use cases may not be immediately clear so let’s dive into some examples and tips for developing a clean, cohesive block theme using custom presets.
A Quick Note on Versioning: As of WordPress 6.6, theme.json has reached version three in its lifecycle, introducing support for block shadows, dimensions, positioning, and some naming adjustments. To use custom presets, the theme.json file should be set to version two or higher.
Defining Custom Presets
Custom presets are added to the theme.json file (or Global Styles) at the top level as an object. There are two different ways to approach this, depending on what the theme requires and the level of organization desired. WordPress will automatically generate the custom properties with one of the following patterns:
- Single Property —
--wp--custom--{key}
- Nested Property —
--wp--custom--{key1}--{key2}
Single Property
Below, we define a single key of “borderColor” (WordPress automatically hyphenates camel-cased names which is consistent with the property naming conventions) and a single hex color value of “#E8E6E6”.
{
"version": 3,
"settings": {
"custom": {
"borderColor": "#E8E6E6"
}
}
}
This generates the custom property: --wp--custom--border-color: #E8E6E6
Nested Properties
For a more refined organization, we can nest our custom properties. We can also create a new object rather than just a single key/value pair. Below we have an example of multiple line-height key/value pairs.
{
"version": 3,
"settings": {
"custom": {
"lineHeight": {
"xs": "1",
"sm": "1.25",
"md": "1.55",
"lg": "1.75"
}
}
}
}
This generates the custom properties:
--wp--custom--line-height--xs: 1
--wp--custom--line-height--sm: 1.25
--wp--custom--line-height--md: 1.55
--wp--custom--line-height--lg: 1.75
Referencing Custom Properties
To reference a defined preset, we can use the special syntax var:preset|{category}|{slug}
. It is also possible to reference presets using the CSS var()
function syntax (e.g., var(--wp--preset--{category}--{slug})
)) but it is more performant to use the WordPress syntax. To use our line-height custom property example from above we would reference it with the “custom” prefix rather than the “preset” prefix like var:custom|{category}|{slug}
.
{
"version": 3,
"settings": {
"custom": {
"lineHeight": {
"xs": "1",
"sm": "1.25",
"md": "1.55",
"lg": "1.75"
}
}
},
"elements": {
"heading": {
"typography": {
"lineHeight": "var:custom|line-height|sm"
}
}
}
}
Here we are setting a small line-height size for all heading elements using our custom preset.
Using Custom Presets
Out of the box, WordPress allows us to define presets within the settings section for the following: color (palette, duotone, gradient), spacing, typography (font size, font family). Blocks that support these settings will use our defined presets in the editor. We can utilize our custom properties throughout our theme.json file to maintain consistency.
Tips
The default presets are great but there are some aspects of site development that are largely ignored. One major area that hasn’t yet been addressed in the theme.json are forms and form elements. It isn’t yet possible to style inputs for example. However, we can leverage custom presets to define form styles and reference these in a custom stylesheet in our theme. In this way we can have many style variations that include unique form styling.
Our theme.json may have the following custom presets:
{
"version": 3,
"settings": {
"custom": {
"border": {
"width": "1px",
"style": "solid",
"color": "var:preset|color|accent-4",
},
"form": {
"input-height": "2.875em",
"input-bg-color": "var:preset|color|accent-5",
"input-bg-color-focus": "var:preset|color|base",
"input-border-color-focus": "var:preset|color|accent-2",
"accent-color": "var:preset|color|accent",
"label-font-size": "var:preset|font-size|small"
}
}
}
}
Color and font size presets are not shown here for brevity.
Our custom theme stylesheet would then reference our custom presets in the following ways:
legend,
label {
font-size: var(--wp--custom--form--label-font-size);
}
input[type="text"] {
border: var(--wp--custom--border--width) var(--wp--custom--border--style) var(--wp--custom--border--color);
height: var(--wp--custom--form--input-height);
background-color: var(--wp--custom--form--input-bg-color);
}
input[type="text"]:focus {
background-color: var(--wp--custom--form--input-bg-color-focus);
border-color: var(--wp--custom--form--input-bg-color-focus);
}
input[type="radio"],
input[type="checkbox"] {
accent-color: var(--wp--custom--form--accent-color);
}
There are many other style definitions we could include here but for brevity, we are just showing a couple of examples.
Note: Custom presets are not accessible to edit within the site editor. These need to be maintained in the theme.json file or any style variations.
If we are using a form plugin such as Gravity Forms, we have the option to customize styles when we add a new form block to a page, however, this method is not ideal as site consistency can easily collapse especially if many people are contributing to the site content. A styleguide that is referenced often could help circumvent this but may not always be used correctly or at all.
We can also ensure consistency and use our custom presets to set default block styles for other forms on the site like the search and comment forms.
Conclusion
There are many potential use cases for custom presets in WordPress block themes, including maintaining consistency with site styles, structure, branding, and defining custom styles for elements like forms. It could even be used for plugin elements or patterns. It’s quite versatile. We’ll have to see how it evolves over time!