Experimental: Global Styles

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 features. A feature can be for example the drop cap text setting for paragraph blocks.

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

The controls are placed inside a separate sidebar panel in the site editor.

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 benefits 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 for the supported blocks.

-The block itself must first have support for the properties that we want to change. At this point, the support is limited to a few basic blocks and styles.

Global styles also makes use of the theme support for editor-color-palette, editor-font-sizes, and editor-gradient-presets.

The data from the theme support and the JSON objects is parsed and reformatted as CSS and CSS variables.

The styles are then added to the editor and the front with wp_add_inline_style.

The CSS is added in approximately the following order:

  1. The Gutenberg block library styles (wp-block-library-css, block-library/style.css)
  2. Custom block styles (register_block_style, wp-block-library-inline-css)
  3. The Gutenberg block library theme styles (wp-block-library-theme-css, block-library/theme.css)
  4. CSS variables (on the :root and .editor-styles-wrapper respectively)
  5. Global styles
  6. Block type styles
  7. Additional styles added by the theme, such as style.css
  8. CSS from the additional CSS customizer option

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

The current status of Global Styles –October 2020

Since the last status update that I wrote in august, global styles and full site editing has been one of the focus areas for the WordPress core editor team.

It is still an experimental feature, but it has support for many more blocks and there is a new, simpler structure for the experimental-theme.json file.

The official documentation for the experimental-theme.json file continues to be improved and you can read it here:

It is not yet possible to change padding and margin, but most basic blocks now have support for background, text and link color. Some blocks supports font size and line height.

All blocks will not have all properties. But expect the support to be updated and improved.

You can refer to these tables to learn which block has support for which property.

The two most common questions I receive about global styles are:

  • Do I have to use CSS variables?
    • Yes. The CSS variables are added for you, and they will be used with the options that the user selects, once the controls are added.
  • Can theme developers limit the Global Style options that the user can change?
    • Not right now, but as far as I know, the intention is to allow theme developers to limit the options.

You probably have a lot of questions right now, but, hold on to them until the end of the lesson. 🙂

The experimental-theme.json file

Updated for Gutenberg 9.1+ on October 20 2020

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:


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

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

{ "property-name": "value" }
Code language: JSON / JSON with Comments (json)

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

"core/heading/h2": { "styles": { ... } }
Code language: JavaScript (javascript)

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

The global scope and the block type scope

The file is separated into two scopes, or contexts:

  • Global scope:
    • Generates CSS variables and defaults for the website.
    • The global scope makes use of settings and styles.
  • Block type scope:
    • Settings that adds default, site wide styles to the supported blocks.
    • Right now, the block type scope only uses styles.

Global settings

The settings section has two parts:
Presets for options that are supported by the block types, and custom settings.

Both presets and custom settings can be explained as settings that creates CSS variables.

They do not change any styles in your theme until the CSS variables are used.

{ "global": { "settings": { "color": { ...this is a preset }, "custom": {" ... this is a custom setting } } } }
Code language: PHP (php)

Global presets

Presets are described using a preset category name and a slug.

In the example below, the preset category is “color”. It also adds the color to the editors color palette.

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

{ "global": { "settings": { "color": { "palette": [ { "slug": "pale-turquoise", "color": "#d1f1f1" } ] } } } }
Code language: JSON / JSON with Comments (json)

The generated CSS variable follows this pattern:


And the output from the example is:

Code language: CSS (css)

Caveat: Presets overrides theme support

This information was updated 10th of October 2020.

Previously, themes were able to add colors to the palette using both the experimental-theme.json file and theme support.

Now, if a color is added to the color palette with a preset, it overrides the theme support for editor_color_palette. This means that the name you have chosen for your color, will not be available in the editor.

Global custom settings

In the preset, the category name that you use will be an existing block property that corresponds to a control.

With custom settings, you are not limited to using properties that the block supports. Custom settings does not have a control in the editor.

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.

Global styles

These are style settings that affect the website.

The color inside the styles uses a property called background to set the default background color for the website:

{ "global": { "styles": { "color": { "background": "var(--wp--preset--color--pale-turquoise)" } } } }
Code language: JSON / JSON with Comments (json)

It uses a CSS variable, and the result is parsed and added as the following CSS:

Code language: JavaScript (javascript)

But style properties are not required to use CSS variables as values.

In this body background color example I am using a color name instead:

{ "global": { "styles": { "color": { "background": "red" } } } }
Code language: JSON / JSON with Comments (json)

And the CSS output will be:

background-color: red;
Code language: HTTP (http)

Block Type 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 block type styles work similarly to global styles.
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.

The second difference is that code is not placed inside the global JSON object. Instead, the block name is used as the first property name:

"core/heading/h2": { "styles": { "color": { "text": "#000" } } }
Code language: JavaScript (javascript)

In the example above, a black text color is applied to the heading block with the level H2. The resulting CSS output is:

h2 { color: #000; }
Code language: CSS (css)

Global Style JSON examples

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

Color Properties

Color properties are placed under styles, color.

The following color properties are available: Background, text, link, and gradient. Check the official documentation to see if they are available for your block.

{ "global": { "styles": { "color": { "background": "#ffffff", "text": "#000", "link": "#000", "gradient": "linear-gradient(180deg,rgb(105,174,231) 0%,rgb(65,128,182) 100%)" } } }, "core/block-name": { "styles": { "color": { "background": "#ffffff", "text": "#000", "link": "#000", "gradient": "linear-gradient(180deg,rgb(105,174,231) 0%,rgb(65,128,182) 100%)" } } } }
Code language: JSON / JSON with Comments (json)

Typography Properties

The typography properties are placed under styles, typography.

The following typography properties are available: fontSize, lineHeight.

The font size preset used in the example is created by the default font sizes in Gutenberg. Calc is used together with the preset since the value is unit less.

{ "global": { "styles": { "typography": { "fontSize": "calc(1px * var(--wp--preset--font-size--normal))", } } }, "core/block-name": { "styles": { "typography": { "fontSize": "2.5rem", "lineHeight": "1.6" } } } }
Code language: JSON / JSON with Comments (json)