The following information is based on the WordPress documentation for ease of reference only. At the time of writing, Global Styles (theme.json) and user interface customizations are being actively developed. And, of course, all of this is still very much in active development. If you notice something has changed or is incorrect, please let me know in the comments!
WordPress Block Theme CSS and Style Settings Guide
Table of contents
Settings
{
"version": 2,
"settings": {
"border": {},
"color": {},
"typography": {},
"layout": {},
"spacing": {},
"outline": {},
"appearanceTools": true | false,
"useRootPaddingAwareAlignments": true | false
}We’ll start with the settings configurations, where we have broken this out into multiple tables for Typography, Colors, Custom, and Spacing.
Remember, these “top-level” styles are applied on the <body> element. And it might be helpful to recall the syntax we’re dealing with:
- CSS Custom properties:
--wp--preset--{preset-category}--{preset-slug} - CSS classes:
.has-{preset-slug}-{preset-category}
Border
The border section enables border controls in the editor UI.
{
"version": 2,
"settings": {
"border": {
"color": true,
"radius": true,
"style": true,
"width": true
}
}| JSON Property | What it Does | CSS Equivalent |
|---|---|---|
settings.border.color | Enables the border color control. | border-color |
settings.border.radius | Enables the border radius control. | border-radius |
settings.border.style | Enables the border style control. | border-style |
settings.border.width | Enables the border width control. | border-width |
Color
The color section sets the theme’s color palettes, gradients, and duotone effects.
{
"version": 2,
"settings": {
"color": {
"palette": {
"slug": "",
"color": "",
"name": "",
},
"gradients": [
{
"slug": "",
"gradient": "",
"name": ""
}
],
"duotone": {
"slug": "",
"color": "",
"name": "",
}
"link": true | false
}
}
}
}| JSON Property | What it Does | CSS Custom Properties |
|---|---|---|
settings.color.pallete.color | Defines color values for use throughout the theme. | --wp–preset--color--{slug} |
settings.color.gradients.color | Defines gradient patterns for use throughout the theme. | --wp–preset--gradient--{slug} |
settings.color.duotone | Defines duotone effects for use throughout the site. | –-wp–preset--duotone--{slug} |
settings.color.link | Enables the setting to change the theme’s default link color in the Site Editor. | –-wp–preset-–color-–link |
Typography
{
"version": 2,
"settings": {
"styles": {
"typography": {
"dropCap": true | false,
"customFontSize": true | false,
"fluid": "<undefined>" | false,
"fontSizes": [
{
"fluid": {
"min": "",
"max": ""
},
"slug": "",
"size": "",
"name": ""
},
],
"fontFamilies": [
{
"fontFamily": "",
"name": "",
"slug": "",
"fontFace": ""
},
],
"lineHeight": true | false,
"fontStyle": true | false,
"letterSpacing": true | false,
"textDecoration": true | false,
"textTransform": true | false,
}
}
}| JSON Properties | What it Does | CSS Custom Property |
|---|---|---|
settings.typography.fontSizes | Defines font size throughout the site. | --wp--preset--font-size--{slug} |
settings.typography.fontFamilies | Defines typographic font use throughout the site. | --wp--preset--font-family--{slug} |
settings.typography.lineHeight | Defines line height to use throughout the site. | --wp--preset--line-height--{slug} |
settings.typography.fontStyle | Defines font style to use throughout the site. | --wp--preset--line-height--{slug} |
settings.typography.fontWeight | Defines font weight for use throughout the site. | --wp--preset--font-weight--{slug} |
settings.typography.letterSpacing | Defines letter spacing for use throughout the site. | --wp--preset--letter-spacing--{slug} |
settings.typography.textDecoration | Defines text decoration for use throughout the site. | –wp-preset–text-decoration–{slug} |
settings.typography.textDecoration.line | Defines link text decoration line for use throughout the site. | --wp-preset--text-decoration--line |
settings.typography.textDecoration.style | Defines link text decoration line style for use throughout the site. | --wp-preset--text-decoration--style--{slug} |
settings.typography.textDecoration.color | Defines link text decoration color for use throughout the site. | --wp–preset--text-decoration--color--{slug} |
settings.typography.textDecoration.thickness | Defines link text decoration line thickness for use throughout the site. | --wp–preset--text-decoration--thickness--{slug} |
settings.typography.textTransform | Defines text transformation type (uppercase, lowercase) for use throughout the site. | --wp--preset--text-transform--{slug} |
Spacing
These settings enable/disable spacing controls for margin and padding in the Site Editor and allow you to set which CSS units to support.
"styles": {
"spacing":{
"padding": true,
"margin": true,
"units": [ "px", "em", "rem", "vh", "vw", "%" ]
}
}The Site and Block Editors include slider form inputs that allow you to set spacing on a scale of predefined values. We can customize that scale with the spacingScale property:
{
"version": 2,
"settings": {
"spacing": {
"spacingScale": {
"operator": "+",
"increment": <number>,
"steps": <number>,
"mediumStep": <number>,
"unit": ""
}
}
}
}| JSON Property | What it Does | Example |
|---|---|---|
settings.spacing.operator | Determines whether the control scales up or down. | + |
settings.spacing.increment | Determines much the spacing changes per step. | 0.25 |
settings.spacing.steps | Determines the number of available steps on the scale. | 6 |
settings.spacing.mediumStep | Sets the midpoint of the range scale. | 1.5 |
settings.spacing.unit | Sets the CSS length unit of the numeric value. | rem |
One more thing we can do with spacing is create CSS custom properties that can be used throughout the theme:
{
"version": 2,
"settings": {
"spacing": {
"spacingSizes": [
{
"size": "",
"slug": "",
"name": ""
}
]
}
}
}| JSON Property | What it Does | Example |
settings.spacing.spacingSizes.size | Sets the custom size value, including unit. | 3.5rem |
settings.spacing.spacingSizes.slug | The slug used in the CSS custom property name. | medium |
settings.spacing.spacingSizes.name | Provides the label for the size in the Site and Block Editor UI. | Medium |
The resulting CSS custom property syntax is: --wp-preset--spacing--<slug>
Layout
{
"version": 2,
"settings": {
"layout": {
"contentSize": "",
"wideSize": "",
"type": "",
}
}
}| JSON Property | What it Does | Generated CSS Property |
|---|---|---|
settings.layout.contentSize | Sets the maximum width of the default content container for pages and posts. | --wp--style--global--content-size |
settings.layout.contentWide | Sets the maximum width of the“wide” content container for pages and posts. | --wp--style--global--wide-size |
settings.layout.type | Determines is the container is default or constrained. |
Appearance tools
{
"version": 2,
"settings": {
"appearanceTools": true | false,
}Setting this to true is a shorthand for enabling the following settings:
{
"version": 2,
"settings": {
"border": {
"color": true,
"radius": true,
"style": true,
"width": true
},
"color": {
"link": true
}
"spacing": {
"margin": true,
"padding": true,
"blockGap": true,
},
"typography": {
"lineHeight": true
}
}
}Root padding-aware alignments
{
"version": 2,
"settings": {
"useRootPaddingAwareAlignments": true | false
}Setting this to true is a shorthand for enabling the following settings:
{
"version": 2,
"settings": {
"spacing": {
"margin": true,
"padding": true
},
}
}Styles
The idea here is that styles are organized by top-level styles (those that set styles on the <body>), global styles (those that set styles on global elements, like headings), and block styles (those that set styles on specific blocks).
{
"version": 2,
"styles": {
// Top-level styles
// etc.
// Global-level styles
"elements": { },
// Block-level styles
"blocks": { }
}
}Top-level styles
{
"version": 2,
"styles": {
// Top-level styles
"border": [],
"color": [],
"spacing": [],
"typography": [],
"filter": "",
"shadow": "",
"outline": []
}
}| Property | Style | CSS equivalent | Additional props |
|---|---|---|---|
border | color | border-color | |
radius | border-radius | ||
style | border-style | ||
width | border-width | ||
top | border-top | color, style, width | |
right | border-right | color, style, width | |
bottom | border-bottom | color, style, width | |
left | bottom-left | color, style, width | |
color | background | background-color | |
gradient | background-image | ||
text | color | ||
spacing | blockGap | gap (in Flexbox and Grid containers) | |
margin | margin | bottom, left, right, top | |
padding | padding | bottom, left, right, top | |
typography | fontFamily | font-family | |
fontSize | font-size | ||
fontStyle | font-style | ||
fontWeight | font-weight | ||
letterSpacing | letter-spacing | ||
lineHeight | line-height | ||
textDecoration | text-decoration | ||
textTransform | text-transform | ||
filter | duotone | filter | |
shadow | box-shadow | ||
outline | color | outline-color | |
offset | outline-offset | ||
style | outline-style | ||
width | outline-width |
Global styles
{
"version": 2,
"styles": {
"elements": {
"buttons": {
"border": {
"radius": ""
},
"color": {
"background": "",
"text": ""
},
"heading": {},
"h1": { },
"h2": { },
"h3": { },
"h4": { },
"h5": { },
"h6": { },
"link": {
"border": { },
"color": { },
"spacing": { },
"typography": { }
}
}
}
}
}
}| JSON Property | What It Does | Where It Is Used |
|---|---|---|
styles.elements.buttons | Defines button element properties (e.g., border, color, etc.) for use throughout the site. | Buttons |
styles.elements.heading | Defines styles of all the headings, the (<h1> to <h6>) elements for use throughout the site. | <h1> to <h6> (all) |
styles.elements.h1 to styles.elements.h6 | Individually defines styles for <h1> to <h6> elements of the heading block for use throughout the site. | <h1> to <h6> (individually) |
styles.elements.link | Defines link <a> element style for use throughout the site. | <a> |
styles.elements.cite | Defines styles for the blockquote.cite, quote.cite classes for use throughout the site. | Quote, Pullquote |
styles.elements.caption | Defines styles for <figcaption> and <caption> elements for Image and Table blocks, respectively, for use throughout the site. | Figure, Table |
styles.elements.spacing.padding | Sets the padding of headings, row, blocks and paragraph blocks for use throughout the site. | Headings, row, blocks, paragraph |
styles.elements.typography | Sets the default typography style for headings and paragraph blocks for use throughout the site. | headings, paragraph |
Global-level styles: interactive elements
{
"version": 2,
"styles": {
"elements": {
"button": {
"color": {
"background": " ",
"text": " "
}
":hover": {
"color": {
"background": " ",
"text": " "
}
},
":focus": {
"color": {
"background": " ",
"text": " "
}
},
":active": {
"color": {
"background": " ",
"text": " "
}
},
":visited": {
"color": {
"background": " ",
"text": " "
}
}
}
}
}
}Note: We can use any already predefined JSON properties in settings presets like typography, outline, shadow, etc., to add styling to any global JSON elements.
| JSON Property | Style | What It Does | CSS Equivalent |
|---|---|---|---|
styles.elements.color | Background | Defines link background color for use entire site. | a:link { background-color } |
| Text | Defines link text color for use entire site. | a:link { color } | |
styles.elements.:hover | Background | Defines hover state link background color for use entire site. | a:hover { background-color } |
| Text | Defines hover state link text color for use entire site. | a:hover { color } | |
styles.elements.:focus | Background | Defines focus state link background color for use entire site. | a:focus { background-color } |
| Text | Defines focus state link text color for use entire site. | a:focus { color } | |
styles.elements.:active | Background | Defines active state link background color for use entire site. | a:active { background-color } |
| Text | Defines active state link text color for use entire site. | a:active { color } | |
styles.elements.:visited | Background | Defines visited state link background color for use entire site. | a:visited { background-color } |
| Text | Defines visited state link text color for use entire site. | a:visited { color } |
Custom
This table shows examples of custom properties you could make using the Custom section of the theme.json file. The CSS custom properties generated by the Custom section use the following syntax: --wp--custom--<variable-name>
| JSON Property | Syntax | Generated Custom Property |
|---|---|---|
settings.custom.spacing.padding | --wp--custom--{padding} | --wp--custom--padding |
settings.custom.typography | --wp--custom--{typography} | --wp--custom--typography |
settings.custom.fontWeight | --wp--custom--{font-weight} | --wp--custom--front-weight |
settings.custom.lineHeight | --wp--custom--{line-height} | --wp--custom--line-height |
settings.custom.someColor | --wp--custom--{some-color} | --wp--custom--some-color |
settings.custom.someParagraph | --wp--custom--{some-paragraph} | --wp--custom--some-paragraph |
Block-level styles
All the global-level styles including the elements may be used to customize the CSS for individual blocks to overwrite the global customization. Block-level styles have precedence over top-level styles (global).
{
"version": 2,
"styles": {
// Top-level styles
// etc.
// Global-level styles
"elements": { },
// Block-level styles
"blocks": {
"core/<BLOCKNAME>": {
// Define or overwrite any global styles
"typography": {
"fontSize": " ",
"fontWeight": "",
"lineHeight": "",
"letterSpacing": "",
"textDecoration": "",
"textTransform": ""
},
// Define or overwrite any global elements styles
"elements": {
"link": {
"typography": {
"textDecoration": ""
},
"color": {
"text": " ",
"background-color": ""
},
":hover": {
"typography": {
"textDecoration": ""
},
"color": {
"text": "",
"background-color": ""
},
},
":focus": {
"typography": {
"textDecoration": ""
},
"color": {
"text": " ",
"background-color": ""
},
},
":active": {
"typography": {
"textDecoration": ""
},
"color": {
"text": " ",
"background-color": ""
},
},
":visited": {
"typography": {
"textDecoration": ""
},
"color": {
"text": "",
"background-color": ""
},
},
},
},
},
// Additional blocks
"core/<BLOCKNAME>": {
"typography": { },
// etc.
}
}
}
}| JSON Property | Style | What It Does |
|---|---|---|
.styles.core.<BLOCKNAME>.typography | font-size | Defines or overwrites the global font size of this block only. |
font-weight | Defines or overwrites the global font weight of this block only. | |
line-height | Defines or overwrites he global font height of this block only. | |
letter-spacing | Defines or overwrites he global letter spacing of this block only. | |
text-decoration | Defines or overwrites he global text decoration of this block only. | |
text-transform | Defines or overwrites the global text transformation of this block only. | |
.styles.core.<BLOCKNAME>.elements.link.typography | text-decoration | Defines or overwrites the global link typography of this block only. |
.styles.core.<BLOCKNAME>.elements.link.color` | background-color | Defines or overwrites the global link background color of this block only. |
color | Defines or overwrites the global link text color of this block only. | |
.styles.core.<BLOCKNAME>.elements.link.:hover.typography | text-decoration | Defines or overwrites the global text decoration of hover link state of this block only. |
.styles.core.<BLOCKNAME>.elements.link.:hover.color | background-color | Defines or overwrites the global background color of hover link state of this block only. |
color | Defines or overwrites the global background color of hover link state of this block only. | |
.styles.core.<BLOCKNAME>.elements.link.:active.typography | text-decoration | Defines or overwrites the global text decoration of active link state of this block only. |
.styles.core.<BLOCKNAME>.elements.link.:active.color | background-color | Defines or overwrites the global background color of active link state of this block only. |
color | Defines or overwrites the global background color of active link state of this block only. | |
.styles.core.<BLOCKNAME>.elements.link.:focus.typography | text-decoration | Defines or overwrites the global text decoration of focus link state of this block only. |
.styles.core.<BLOCKNAME>.elements.link.:focus.color | background-color | Defines or overwrites the global background color of focus link state of this block only. |
color | Defines or overwrites the global background color of focus link state of this block only. | |
.styles.core.<BLOCKNAME>.elements.link.:visited.typography | text-decoration | Defines or overwrites the global text decoration of visited link state of this block only. |
.styles.core.<BLOCKNAME>.elements.link.:visited.color | background-color | Defines or overwrites the global background color of visited link state of this block only. |
color | Defines or overwrites the global background color of visited link state of this block only. |
For use case examples of block-level CSS customization, you may refer to the latest Twenty Twenty-Three theme and other recent block themes in the theme directory.
Wrapping up
You made it through this compelete guide to WordPress block theme CSS and settings! We started with a brief introduction that compares WordPress block themes to the “classic” PHP templating system. From there, we talked a bit about JSON because, funny enough, that’s how we “write” CSS in WordPress block themes.
Then there’s theme.json the actual file where all of those styles are defined, much like style.css was for classic PHP themes. The file is tightly structured into sections for toggling WordPress settings and defining CSS globally throughout a block theme.
And once we’re done defining a block theme’s settings and styles, the WordPress Style Engine takes over, processing our JSON into a nicely organized set of CSS styles used in the theme.
WordPress Block Theme CSS and Style Settings Guide
It’s crazy just how different block themes are when it comes to defining and managing styles in WordPress! All of this is still in active development, and we are likely to see new features and options added to theme.json.
See something that’s new or has changed? Please let me know in the comments!
