Global Styles

Level: Beginner, intermediate

Estimated reading time: 10 minutes

Updated for Gutenberg 10.3 on April 7, 2021

What are Global Styles?

Global styles is a system created to help users change the overall style of their site, without having to edit individual blocks or pages.

Users will be able to select a body background color or change the line-height of all their headings from one place. Styles added to individual blocks will still override the global styles.

Global styles has also been created to make it easier for developers to style their blocks both in the editor and the front.

Even though it is called Global Styles, it is not only used for styles but also for enabling or disabling settings and features. A feature can be for example the drop cap.

Global Styles are still experimental. If you are using the latest version of Gutenberg and enable a full site editing theme you can preview and test the new controls.

The controls are placed inside a separate sidebar panel in the site editor. Open the sidebar by clicking on the Aa icon.

Global styles sidebar

Who benefits from Global Styles?

Besides the users who will have more possibilities to change the look of their sites, global styles also benefit new theme developers.

The new controls will drastically reduce the need for custom solutions for styling, for example, a theme options panel or customizer settings.

-It lowers the entry barrier for new theme developers while allowing control of the styles.

How does global styles work?

Global styles work with the help of a new theme settings file called experimental-theme.json. Theme developers can use JSON format to define defaults for both the website and blocks.

The data from the JSON objects are parsed and reformatted as CSS and CSS variables.
The styles are then added to the editors and the front.

In earlier versions of Gutenberg, a block needed to add support for style properties before these properties could be controlled with the theme.json file. This is no longer the case. All blocks can now be styled.
Block support is still used to add a user facing control in the block settings sidebar.

For those who are interested in seeing how the data is fetched, stored and parsed, see the global-styles.php file in the Gutenberg plugin.

The way CSS is loaded was improved significantly in Gutenberg version 9.6. Gutenberg now only loads the styles of the blocks that are used on a page.
If you are interested in learning about the continued work to improve the performance, see https://github.com/WordPress/gutenberg/pull/28358

The experimental-theme.json file

A file called experimental-theme.json is created and placed inside the main folder of the theme. The file will likely be renamed to theme.json once global styles are no longer experimental.
If you have already taken the block attributes lesson, you may recognize the format.

If you are new to JSON and want to read more about it first, I recommend these resources:
https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/JSON
https://www.json.org/json-en.html

You start the file with two curly brackets, { } and all the content will be placed inside these brackets.

You then use a format with property names and values, encased in double quotes and separated with a colon:

{
"property-name": "value"
}

The property name can be a block name or a setting:

"core/heading/h2": {
	"typography": {
		...
	}
}

These may be nested in several levels, as you will see in the examples below.

Main sections and sub sections

The file is separated into two main sections: settings and styles.

There are also sections for other type of information like post templates, template parts, and skip links. The format of these are still subject to change.

  • Settings:
    • The editor configuration. Enables or disables features like custom font sizes, custom padding and colors.
    • Defines preset values such as color palettes, that generates CSS variables that can be used by the theme.
    • Has two sub sections:
      • Defaults -Settings that apply to all blocks, unless overridden.
      • Per block -Overrides the default settings.
  • Styles:
    • Applies styling to the website or the blocks, with or without the generated CSS variables.
    • Has two sub section:
      • Root -Applies styles to the website, for example body background color.
      • Per block -Overrides root styles and applies styles to blocks.
{
	"settings": {
		"defaults": {
		}
	},
	"styles": {
		"root": {
		},
                "core/paragraph": {
                }
	}
}

Settings presets

Presets are described using a preset category. The categories are block properties that corresponds to a control in the editor. Some preset categories have sub categories.

In the example below the preset category is color and the sub categories of color are palette and gradients.

Presets with multiple values are placed inside an array. The properties are separated with a comma:

{
"settings": {
	"defaults": {
		"color": {
			"palette": [
				{
				"slug": "purple",
				"color": "#D1D1E4",
				"name": "Purple"
				},
				{
				"slug": "red",
				"color": "#E4D1D1",
				"name": "Red"
				}

			],
			"gradients": [
				{
				"slug": "purple-to-red",
				"gradient": "linear-gradient(160deg, var(--wp--preset--color--purple), var(--wp--preset--color--red))",
				"name": "Purple to Red"
				}
			]
		   }
            }
      }
}

If you look at the gradient above, you can see that it uses the purple and red colors that were declared in the palette.
Each preset generates a CSS variable using this naming convention:

--wp--preset--{preset-category}--{preset-slug}

And the output from the example is:

--wp--preset--color--purple: #D1D1E4;
--wp--preset--color--red: #E4D1D1;

--wp--preset--gradient--purple-to-red: linear-gradient(160deg, var(--wp--preset--color--purple), var(--wp--preset--color--red));

Layout and content width

The layout category replaces add_theme_support( 'align-wide' ); and defines the width of the content.
contentSize -The default block width.
wideSize -The width of blocks with the wide align setting enabled.

This setting does not output CSS variables.

"layout": {
	"contentSize": "840px",
	"wideSize": "1100px"
}

Custom presets

With custom presets, you are not limited to using properties that the block supports.
A custom preset can be anything. If you want to handle all your themes CSS variables in one settings file, you can use the experimental-theme.json to create custom CSS variables that you can use anywhere in your CSS.

{
	"settings": {
		"defaults": {
			"custom": {
				"spacing": "14px"
			}
		}
	}
}

Custom preset generates a CSS variable using this naming convention:

--wp--custom--slug

Because of this, you should not use -- in your slug or values.

The output from the example is:

--wp--custom--spacing: 14px;

Enable or disable features

Typography features

  • customLineheight: Opt-in, set to true to enable.
  • customFontSize: Let the user select a custom size value. Enabled by default, set to false to disable.
  • customFontWeight: Enabled by default, set to false to disable.
  • customFontStyle: Enabled by default, set to false to disable.
  • dropCap: Let the user add a drop cap. Enabled by default, set to false to disable.

Example code:

{
	"settings": {
		"defaults": {
			"typography": {
				"customLineHeight": true,
                                "customFontSize": false,
                                "dropCap": false,
                        }
		}
	}
}

Color

  • custom: Let the user select custom colors using the color picker. Enabled by default, set to false to disable.
  • customGradient: Let the user select custom gradients using the color picker. Enabled by default, set to false to disable.
  • link: Let the user select link text color. Used for all link states. Opt-in, set to true to enable.
{
	"settings": {
		"defaults": {
			"color": {
				"custom": false,
				"customGradient": false,
				"link": true
			}
		}
	}
}

Padding

Enable support for custom padding for cover and group blocks:

{
	"settings": {
		"defaults": {
			"spacing": {
				"customPadding": true
			}
		}
	}
}

Enable custom units for the padding:

{
	"settings": {
		"defaults": {
			"spacing": {
				"customPadding": true,
				"units": [ "px", "em", "rem", "vh", "vw" ]
			}
		}
	}
}

Border

Enable support for border radius for group blocks and images.

This property does not have a visible control in the editor.

{
	"settings": {
		"defaults": {
			"border": {
				"customRadius": true
			}
		}
	}
}

Styles

Root styles

Root styles are styles that affect the website. You can use any valid CSS value.
In the example I am using a color value for the background, and a global styles preset for the text.

The preset is defined in the settings, but the code in the example is truncated.

{
	"settings": { ... },
	"styles": {
		"root": {
			"color": {
			"background": "#FFF",
			"text": "var(--wp--preset--color--purple)"
			}
		}
	}
}

And the CSS output is:

:root {
	background-color: #FFF;
	color: var(--wp--preset--color--purple);
}

Block Styles

Block type styles are default styles for blocks. The styles are applied to all instances of a block type.

Block type styles overrides global styles.
Additional styles added by the theme can be used to override styles for individual blocks.
The styles can be overwritten per block, by selecting the block in the editor and adjusting the options in the block sidebar.

For block styles, the category name is always an existing property. A block must first have support for a property before that property can be changed.

The available properties can be found in the official documentation.

In the example, the red color is applied to the H2 heading block:

{
	"settings": {...},
	"styles": {
		"root": {...},
		"core/heading/h2": {
			"color": {
				"text": "var(--wp--preset--color--red)"
			}
		}
	}
}

The resulting CSS output is:

h2 { color: var(--wp--preset--color--red); }

Additional sections

Template part areas

In the site editor, there are two optional template part areas: header and footer.
A template part that has been designed as a header can be assigned to the header area.
This helps users select the correct templates when they are creating or editing their website.

This section is on the root or base level of the experimental-theme.json file (not to be confused with Styles -> root).

The section name is templateParts, followed by the name and slug of the template part, and the name of the area:

"templateParts": [
	{
		"name": "header",
		"area": "header"
	},
	{
		"name": "footer",
		"area": "footer"
	}
]

wp_template_part_area is a taxonomy for the wp_template_part post type.

More template part areas are likely to be added later.

Custom templates

A custom template in this scenario is a template that can be selected in the block editor under the Page Attributes option.

In a traditional PHP based theme, the required information would be placed in the file header of the template file. With full site editing, templates are added to the experimental-theme.json file at the base level.

The section name is customTemplates, and the first key is the name and slug of the template.
In the example, the block template file is called page-home.html.
title is the template name that is visible in the editor.
postTypes is an array of supported post types. The default is page.

"customTemplates": [
	{
		"name": "page-home",
		"title": "Page without title",
		"postTypes": [ "page", "post" ]
	}
]

Global Style JSON examples

These examples describe the nesting of the different properties that are needed for the global styles to work.

Creating presets

Colors

{
	"settings": {
		"defaults": {
			"color": {
				"palette": [
					{
						"slug": "purple",
						"color": "#D1D1E4",
						"name": "Purple"
					},
					{
						"slug": "red",
						"color": "#E4D1D1",
						"name": "Red"
					}
				],
				"gradients": [
					{
						"slug": "purple-to-red",
						"gradient": "linear-gradient(160deg, var(--wp--preset--color--purple), var(--wp--preset--color--red))",
						"name": "Purple to Red"
					},
					{
						"slug": "red-to-purple",
						"gradient": "linear-gradient(160deg, var(--wp--preset--color--red), var(--wp--preset--color--purple))",
						"name": "Red to Purple"
					}
				]
			}
		}
	}
}

Typography

Example from TT1 Blocks and Q, including fontSizes and fontFamilies:

{
	"settings": {
		"defaults": {
			"typography": {
				"fontSizes": [
					{
					"slug": "gigantic",
					"size": "144px",
					"name": "Gigantic"
					}
				],
				"fontFamilies": [
					{
					"fontFamily": "-apple-system,BlinkMacSystemFont,\"Segoe UI\",Roboto,Oxygen-Sans,Ubuntu,Cantarell,\"Helvetica Neue\",sans-serif",
					"slug": "system-font",
					"name": "System Font"
					}
				]
			}
		}
	}
}

Applying color properties

The following color properties are available: Background, text, link, and gradient. You can not use background and gradient at the same time.

{
	"settings": {...},
	"styles": {
		"root": {
			"color": {
				"background": "#FFF",
				"text": "var(--wp--preset--color--purple)",
				"link": "var(--wp--preset--color--red)",
			}
		},
		"core/group": {
			"color": {
				"text": "var(--wp--preset--color--purple)",
				"link": "var(--wp--preset--color--red)",
				"gradient": "var(--wp--preset--gradient--purple-to-red)",
			}
		}
	}
}

Applying typography properties

The typography properties are not as widely supported as the colors.

The following properties are available: font family, font size, font style, font weight, line height, text decoration, text transform.

The font size preset used in the example is created by the default font sizes in Gutenberg.

{
	"styles": {
		"root": {
			"typography": {
				"fontSize": "var(--wp--preset--font-size--normal)"
			}
		},
		"core/heading/h1": {
			"typography": {
				"fontSize": "var(--wp--preset--font-size--huge)"
			}
		},
		"core/heading/h2": {
			"typography": {
				"fontSize": "var(--wp--preset--font-size--large)"
			}
		}
	}
}

CSS output:

:root {
	font-size: var(--wp--preset--font-size--normal);
}

h1 {
	font-size: var(--wp--preset--font-size--huge);
}

h2 {
	font-size: var(--wp--preset--font-size--large);
}