The developer experience of WordPress presets

In the lingo of the WordPress block editor, presets are the set of values that are shown to users in different style categories: colors, duotone values, font sizes, gradients.

Presets are an important part of a WordPress theme because they’re presumably tied to the theme style choices. When having presets available, users can create content that is in line with the look&feel of the theme.

WordPress 5.8 came with a new API called theme.json, see the developer note, the specification document, and the results of the block theme authors survey. Among other things, it creates a new mechanism to register presets.

How to make presets work before WordPress 5.8

For simplicity, I’ll show how to register the color palette preset with only two values: green & blue. The mechanics are the same for any other preset type or number of values.

1. Create the CSS for the presets. This tends to live in a specific CSS file, for example, colors.scss:

.has-green-color { color: #D1E4DD; }
.has-green-background-color { background: #D1E4DD; }

.has-blue-color { color: #D1DFE4; }
.has-blue-background-color { background: #D1DFE4; }

2. Use the colors in the stylesheet for the editor at style-editor.scss and in the stylesheet for the front at style.scss. This is simplified as a single step but it usually involves a few files and building SASS into CSS via some scripts:

@import "colors";

// Other presets, styles, etc

3. Enqueue the stylesheets for the editor and front. This lives in functions.php.

add_action( 'wp_enqueue_scripts', function(){
    wp_enqueue_style( 'my-theme-style-front', 'path/to/style.css';
} );

add_action( 'after_setup_theme', function() {
  add_editor_style( 'style-editor.css' );
} );

4. Declare the preset values and labels for the UI controls to use them. Also mark strings for internationalization. This lives at functions.php as well:

add_theme_support(
    'editor-color-palette',
        array(
            array(
                'name'  => esc_html__( 'Green', 'my-theme' ),
                'slug'  => 'green',
                'color' => '#D1E4DD',
            ),
            array(
                'name'  => esc_html__( 'Blue', 'my-theme' ),
                'slug'  => 'blue',
                'color' => '#D1DFE4',
            )
        )
    )
);

How to make presets work after WordPress 5.8

The method above still works, but there’s a new mechanism to register presets via the theme.json file:

{
    "version": 1,
    "settings": {
        "color": {
            "palette": [
                {
                    "name": "Blue",
                    "slug": "blue",
                    "color": "#D1DFE4"
                },
                {
                    "name": "Green",
                    "slug": "green",
                    "color": "#D1E4DD"
                }
            ]
        }
    }
}

That’s it. All of it.

Theme authors declare what colors they want to expose to the users and the WordPress engine figures out what needs to be done: passing the data to the UI controls, process the labels for translation, create the CSS for all the properties that use colors, enqueue the CSS in the front and the editors, etc. Whether you’re using a block-based theme or a classic one it works the same.

And more: presets per block

The goal of the theme.json is to abstract the WordPress mechanics so theme authors can focus on design. You can do the same things you did with add_theme_support in a simpler way. And you can also do more things.

For example, providing a different color palette per block was not possible via add_theme_support. It’s now possible.

Let’s say that in the “Site Title” block you want to show only colors that match your logotype, for branding purposes. You still want any other block to only have the original green & blue. This is how you do it:

{
  "version": 1,
  "settings": {
    "color": {
      "palette": [
        {
          "name": "Blue",
          "slug": "blue",
          "color": "#D1DFE4"
        },
        {
          "name": "Green",
          "slug": "green",
          "color": "#D1E4DD"
        }
      ]
    },
    "blocks": {
      "core/site-title": {
        "color": {
          "palette": [
            {
              "name": "Red",
              "slug": "red",
              "color": "#CD5C5C"
            },
            {
              "name": "Yellow",
              "slug": "yellow",
              "color": "#FFDE2B"
            }
          ]
        }
      }
    }
  }
}

Help us improve

By sharing this example I hope to interest you in the theme.json horizon. What we have is promising but it’s also not finished! I encourage people to try it out and report the things that don’t work so well yet or the things they wish it had. Join the theme author surveys. Give feedback through any channel of your choice. Help us improve.