The Complete Newbie’s Guide to theme.json in WordPress

If you’re new to WordPress Block Themes, you may what have heard about theme.json, but you are confused what it actually does.

While it may seem a little daunting, it’s actually an incredibly powerful tool that you can use to customize your WordPress website. In essence, theme.json does two main things:

• Theme.json allows you to configure global styles across your entire website
• Theme.json lets you curate the options available in the Gutenberg block editor.

In this guide, we’ll demystify theme.json, making it easy for even complete beginners to understand. By the end, you’ll have a solid understanding of how theme.json works and how to use it to take your WordPress site to the next level.

What is theme.json?

theme.json is a configuration file that plays a critical role in the Full Site Editing (FSE) feature in WordPress. It allows you to control the global settings and styles across your website. In other words, it’s like a central control panel for your website’s appearance.

Understanding Global Settings

The first section of the theme.json file is the Global Settings. Here, you can manage settings that apply to all blocks on your website. Blocks are the building blocks (pun intended) of your WordPress site, like paragraphs, images, or headers.

The settings you define in this section will be applied to all blocks unless a particular block overrides them. For instance, if a block doesn’t implement a feature like dropCap, the theme cannot enable it for that block through theme.json.

One exciting feature within global settings is appearanceTools. This property, when set to true, enables additional features like border color, radius, style, width, link color, and more.

Leveraging Presets

Presets are another part of the settings section in theme.json. They are predefined values shown to the user via some UI controls. By defining them through theme.json, the engine can automatically translate the preset name or enqueue the corresponding CSS classes and custom properties. Examples include color.duotone and color.gradients.

Creating Custom Properties

In addition to creating CSS Custom Properties for the presets, theme.json also allows themes to create their own custom properties. This feature is especially useful for theme developers, as it allows for greater customization without having to enqueue additional CSS files.

Examples of Settings

To give you an idea of what you can do with settings in theme.json, here are a few examples:

• Enable custom colors only for the paragraph block.
• Disable border radius for the button block.
• Provide the group block a different color palette than the rest.

Styling Your Blocks

The theme.json file also has a styles section that allows for more precise control of the visual aspects of blocks. This section enables a theme to define styles that will apply to the whole site, to specific block types, or to a block style variation.

Curating the Gutenberg Block Editor Options with theme.json

Beyond configuring global styles, the other powerful feature of theme.json is the ability to curate the options available in the Gutenberg block editor.

The Gutenberg block editor in WordPress uses blocks (like paragraphs, images, buttons, etc.) to build content. Each block comes with its own set of configurable options. However, as a theme developer or website owner, you might want to limit or extend these options to maintain design consistency or provide additional flexibility.

That’s where theme.json comes into play. With this file, you can precisely control which settings are available for each block type. For example, you can enable custom color options only for the paragraph block or disable border radius for the button block.

Here’s an example of how to enable custom colors only for the paragraph block:

{
    "version": 2,
    "settings": {
        "color": {
            "custom": false
        },
        "blocks": {
            "core/paragraph": {
                "color": {
                    "custom": true
                }
            }
        }
    }
}

And here’s how to disable border radius for the button block:

{
    "version": 2,
    "settings": {
        "blocks": {
            "core/button": {
                "border": {
                    "radius": false
                }
            }
        }
    }
}

This granular control over block settings can help maintain design consistency across your site and simplify the editing experience for content creators. It’s another way theme.json elevates your WordPress site’s customization capabilities.

Conclusion

Embracing theme.json may seem daunting at first, but it offers an unprecedented level of control over your WordPress site’s appearance. As a newcomer, don’t worry about mastering everything at once. Start by playing around with the global settings, presets, and custom properties. As you become more comfortable, you can dive into the more advanced features. Happy customizing!