If you’ve worked with the block or site editor you’ve probably noticed that WordPress generates CSS variables based on what you enter in theme.json. This includes things like your color palette, spacing values, font sizes, font families, and more. In this post I’ll show you how you can add your own custom CSS variable definitions to supplement the ones that core generates for you and explain why you might want to do this in your theme.
Your theme’s theme.json file has a number of top level properties and the most commonly used of these in settings. This key contains a number of other properties that you can use to define your color palette, font sizes, spacing options, and more. Certain properties in the settings property (like color.palette, typography.fontSizes, spacing.spacingSizes and others) will be used to generate CSS variables automatically.
If you’re new to the concept of CSS variables (aka Custom Properties) in general, I would strongly suggest you check out this MDN article that explains how they work.
The variables generated from these built-in settings properties all have the same prefix: --wp--preset--<property>–. So if you have a color in your palette named brand then the CSS variable generated would be named: --wp--preset--color--brand. Similarly if you had a font size like “xl” the variable would be --wp--preset--font-size--xl.
There is a special property in settings called custom which allows you to define your own CSS variables directly and include those CSS variable definitions automatically anywhere else that the core CSS variables are added. By adding properties to the custom property, you have a simple and consistent way to add new CSS variables beyond the ones WordPress generates for you.
Now let’s look at a practical example for how you might use these.
A practical example: adding duration values
Imagine you’re building a new site and you want to use a consistent set of durations for your transitions and animations. You have 3 total values you want to use: 150ms, 200ms, and 300ms.
If you were authoring the CSS variables yourself, you might add them to your stylesheet like this:
:root {
--<your_namespace>-duration-150: 150ms;
--<your_namespace>-duration-200: 200ms;
--<your_namespace>-duration-300: 300ms;
}When authoring CSS variables, it’s a good practice to give similar values a common prefix like we did above. Each of the values begins with a namespace which is a common prefix that you might use for all CSS variables in your project to prevent name conflicts. From there it includes -duration- followed by the name of the variable (100, 200, 300).
This is easy enough to do, but you have to remember to correctly name the variables as well as make sure the stylesheet that defines them loads in all of the places it needs to load. For instance, in the block editor, your CSS variables that are normally defined on the :root selector in your own stylesheet will be scoped to the editor-styles-wrapper class as long as you’ve added your stylesheet to the editor properly.
So you could just add these yourself, but it’s a lot of extra work. Plus it doesn’t allow WordPress to help you out by including the variables in places they might need to be that maybe you didn’t think of.
A simpler alternative is to just define these variables in your theme’s theme.json file. The variables will be included anywhere all of the other theme.json variables are included, so all you need to do is place them here and you don’t have to do anything else to get them on the page and usable in your stylesheets.
Adding your own variables using the custom property
Here’s an example of how it would look to add these variables to theme.json:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
...
"custom": {
"duration": {
"100": "100ms",
"200": "200ms",
"300": "300ms"
}
}
}
} This outputs 3 variables that look like this:
:root {
--wp--custom--duration--100: 100ms;
--wp--custom--duration--200: 200ms;
--wp--custom--duration--300: 300ms;
}When you add values to the custom property, it will generate a CSS variable with different prefix than the preset settings above: --wp--custom--<property>. If the value of a given property is an object, then the keys of that object are added to the variable name and separated with a double hyphen --.
If the value for a property is an object, the keys of that object are appended to the variable name. So in our example, we added the duration property and it’s value is an object that has 3 other properties in it, so each of those 3 variables has the same prefix.
To add a new value later you would just add another property after “300” with whatever duration you want. Sweet!
The properties you enter here will be parsed into a consistent kebab-case format. This applies in a few specific situations:
- camelCase names will become kebab-case
- textShadow becomes “text-shadow”
- Numbers will be treated like an uppercase letter
- abc123 becomes “abc-1-2-3”
Tips for using your new CSS Variables
- You can override these custom values (or other settings) in a child theme
- You can reference these values using the theme.json shorthand (
var:custom|duration|100) or standard syntax in theme.json - You can use these custom variables to define values of other settings/presets in theme.json. This is handy if you want to define a bunch of colors but not make them all visible in the color picker.