Starting in WordPress 5.8, a new tool — “theme.json” — is available to use in your theme. Maybe you’re hearing about it for the first time, or maybe you’re testing and developing themes with it already. Either way, I’m glad you’re here because it’s an exciting time for WordPress themes.
This post provides a quick introduction to this new framework, and describes what’s possible by sharing a few practical tips and examples.
What’s theme.json?
Technically, theme.json is just a file that lives at the top-level of a theme’s directory.
Conceptually, it’s a major shift in how themes can be developed. Theme authors now have a centralized mechanism to tailor the WordPress experience for site authors and visitors. Theme.json provides theme authors fine-grained control over global styles, block styles, and the block editor settings.
By providing these settings and controls in a single file, theme.json provides a powerful framework that brings together many aspects of theme design and development. And as the block editor matures and adds more features, theme.json will shine as the backbone for themes and the editor to work together.
Why Use it?
It’s the future! But if you’re like me, you might need something more tangible to be convinced. Here are a few reasons why you might use theme.json today:
Control editor settings like color, typography, spacing, and layout, and consolidate where these settings are managed.
Guarantee that styles apply correctly to blocks and elements across your site.
Reduce the amount of boilerplate CSS a theme used to provide. Theme.json won’t replace your stylesheet completely — there will be instances where CSS is needed to give your theme that extra flare (transitions, animations, etc.). But it can greatly reduce the base CSS needed from the theme.
I hope this gives you a sense of what’s possible and where themes are going. The above examples just scratch the surface of what kinds of theme design configurations are possible, and I’m very excited to see what theme authors create.