A theme’s global styles are defined in a file called theme.json
.
It’s a complicated file in JavaScript Object Notation (JSON ) format.
- There are many settings which can have lots of values.
- You have to get the structure and the syntax correct.
- If you make any mistake with the syntax then the Global Styles aren’t set.
- You don’t get any messages.
- Everything just looks all wrong.
- If you do make any changes, use a JSON validator to check your syntax.
- And then check it again for semantics.
The level 1 parts of the theme.json
file are:
{
"version": 1,
"settings": {},
"styles": {},
"customTemplates": {},
"templateParts": {}
}
Level 1 | Level 2 | Level 3 | Level 4 | Values |
---|---|---|---|---|
version | 1 – the first official version |
Level 1 | Level 2 | Level 3 | Level 4 | Values |
---|---|---|---|---|
settings | ||||
border | customColor, customRadius, customStyle, customWidth | true / false | ||
color | custom, customGradient, duotone, gradients, link, palette | |||
spacing | customPadding | true / false | ||
units | [ px, em, rem, vh, vw ] | |||
typography | ||||
customFontSize | true / false | |||
customFontWeight | true / false | |||
customFontStyle | true / false | |||
customLineHeight | true / false | |||
dropCap | true / false | |||
fontFamilies | [ fontFamily, slug ] | |||
fontSizes | [ name,size,slug ] | |||
layout | ||||
contentSize | eg 800px | |||
wideSize | eg 1200px | |||
custom | eg line-height | eg body, heading | ||
blocks | blockname eg core/paragraph | border,color,custom,layout,spacing,typography | as for level2 |
Level 1 | Level 2 | Level 3 | Level 4 | Values |
---|---|---|---|---|
styles | ||||
border | color, radius, style, width | value | ||
color | ||||
background | var( –wp–preset–color–background ) | |||
gradient | ||||
text | var( –wp–preset–color–foreground ) | |||
spacing | padding | top, right, bottom, left | value | |
typography | ||||
fontFamily | value | |||
fontSize | value | |||
fontStyle | value | |||
fontWeight | value | |||
lineHeight | value | |||
textDecoration | value | |||
textTransform | value | |||
elements | ||||
link | border, color, spacing, typography | |||
element name eg h1 | ||||
blocks | block name eg core/group | border, color, spacing, typography, elements | as for level 2 | |
as for root |
Level 1 | Level 2 | Level 3 | Level 4 | Values |
---|---|---|---|---|
customTemplates[] | ||||
name | eg single-full | |||
title | eg Full width stuff | |||
postTypes[] | page, post, CPT |
Level 1 | Level 2 | Level 3 | Level 4 | Values |
---|---|---|---|---|
templateParts[] | ||||
name | eg header | |||
area | eg header |
The theme.json
file uses settings
to define the options that are supported in the editor, and styles
to set default values and/or override the setttings at a global level.
The Site Editor Global styles panel defines the user’s modification to the global styles set by the theme.
Each block can be individually customised, depending on the options presented.
Examples

Typography
The Global Styles Root panel shows the defaults for all blocks.
Typography controls include:
- Font family –
styles.typography.fontFamily
- Font size –
styles.typography.fontSize
- Line height (not shown) –
styles.typography.lineHeight
- Appearance –
styles.typography.fontWeight
Styling header, footer and other areas
I don’t know how to do this using theme.json
.
References
For details of how the values defined in theme.json
work together to define the settings of the block editor see
Block Editor Handbook: Global Settings (theme.json ), the source of which is
https://github.com/WordPress/gutenberg/blob/trunk/docs/how-to-guides/themes/theme-json.md