Global styles – theme.json

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": {}
version section of theme.json
Level 1 Level 2 Level 3 Level 4 Values
border customColor, customRadius, customStyle, customWidth true / false
color custom, customGradient, duotone, gradients, link, palette
spacing customPadding true / false
units [ px, em, rem, vh, vw ]
customFontSize true / false
customFontWeight true / false
customFontStyle true / false
customLineHeight true / false
dropCap true / false
fontFamilies [ fontFamily, slug ]
fontSizes [ name,size,slug ]
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
settings section of theme.json
Level 1 Level 2 Level 3 Level 4 Values
border color, radius, style, width value
background var( –wp–preset–color–background )
text var( –wp–preset–color–foreground )
spacing padding top, right, bottom, left value
fontFamily value
fontSize value
fontStyle value
fontWeight value
lineHeight value
textDecoration value
textTransform value
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
style section of theme.json
Level 1 Level 2 Level 3 Level 4 Values
name eg single-full
title eg Full width stuff
postTypes[] page, post, CPT
customTemplates section of theme.json
Level 1 Level 2 Level 3 Level 4 Values
name eg header
area eg header
templateParts section of theme.json

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.



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.


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

JSONLint – the JSON validator


Page List

Page Tree ( shortcode )

© Copyright Herb Miller, Bobbing Wide 2021