Decoding WordPress: New Theme Configuration Options with Theme.JSON File

New theme configuration options in WordPress are making it easier than ever before to modify the appearance of your site to your specific and unique needs. What’s more, the ability to convert classic themes to block themes is adding even more user-friendly functionality.

In this blog post, the fourth in our “Decoding WordPress” series, we’ll discuss both of these developments, including what they are and how they can make it easier for you to have a beautiful, tailored site whether you have beginner or intermediate WordPress development skills.

An Overview of WordPress Themes and Templates

Before going over the newest options for configuring your theme by utilizing the newest options made possible by a file called theme.json, we’ll get acquainted with what it actually means to configure a theme. In order to help our understanding of that, let’s first clarify the difference between a theme and a template in WordPress, since there’s often some confusion about it, especially if you’re a novice.

A theme is the complete design and foundation for your site’s cohesive look and feel. It includes things like color palettes, typography, page layouts, margins, line spacing, headers and footers, sidebar positioning, and other elements. When you choose a theme and install it, all of these elements are automatically installed as well. There are virtually countless numbers of free and paid themes available.

A template, however, is a single-page layout within a sitewide theme. And although modifications may be made to a template, they’re only applied to any of the pages that use that template, not to the entire site. Elements like customizing your blog’s layout, building landing pages, and giving other content a distinctive look are examples of what you can achieve through templates.

So, What Are Theme Configuration Options, Then?

Theme configuration options are admin pages that come with some WordPress themes. These admin pages allow you to customize the settings of your installed theme without having to modify any theme files or get bogged down with altering code. Some of these admin pages can offer a few options, while others may have many, many more. If you’re a beginner, the relative simplicity of an admin page versus the more complicated route can be a welcome time — and sanity saver.

If your goal is only to enhance or change functionalities within a theme, you can greatly simplify matters by installing a plugin rather than reconfiguring the entire theme. However, if you’re wanting to modify theme styles and block settings across your entire site, reconfiguring things through customizing is what you’ll need to do.

What the Heck is JSON?

To customize your WordPress theme when it doesn’t include an admin page, you’ll need to create and add a theme.json configuration file to the theme. But what is JSON? The acronym stands for JavaScript Object Notation, which is an open text-based data interchange format that can be read by both humans and machines and isn’t linked to any specific programming language. Its most common use is for transmitting data in web applications.

theme.json support was added to WordPress in version 5.8, and doesn’t work with older versions of WordPress unless you activate the Gutenberg plugin. (The Gutenberg editor was officially released in 2018 alongside WordPress 5.0.)

Some of the customization options you can choose from within theme.json include:

• Enabling or disabling features like drop caps, block padding, margins, and custom line heights
• Adding multiple color palettes, gradients, and duotone filters for photos
• Modifying font sizes
• Adding default widths for content
• Managing custom CSS (cascading style sheet) properties. CSS is used to define visual appearance and formatting of HTML documents.
• Assign template parts to template part areas

As Gutenberg development moves forward, the options that are available with theme.json in WordPress differ between version 5.8 (where version 1 of theme.json is used) to version 5.9+ (where version 2 of theme.json is used) as well as the Gutenberg plugin.

Options Explained

With these more granular customization options now within the reach of beginner and intermediate WordPress developers, let’s talk about both what they are and why they could be beneficial to you.

Enabling or disabling features like drop caps, block padding, margins, and custom line heights

Drop caps (a style technique in which the first letter of a paragraph has a larger font size), block padding (the space inside the block that lies between the element/content and the block’s border, and that surrounds all sides of the element), margins, and custom line heights can give your pages a more distinctive and even formal look, depending on how you manage to style them.

Adding multiple color palettes, gradients, and duotone filters for photos

The right color palette – or multiple palettes – can help to define and enhance the marketable identity of both your brand and your site, and gradients (backgrounds of two colors that transition into one another) can give your site a more dynamic identity than only using solid colors for the pages on your site. Duotone filters can be applied to photos you’ve uploaded to your site, and reduce the number of colors in the photo to just two – one for the dark parts of the photo, another for the light parts. Using these resources within your WordPress theme’s settings, your site’s overall color schemes can be formal, moderate, or avant-garde – limited only by your imagination.

Modifying font sizes

Sometimes, the fonts in your chosen theme may suit the specific identity, tone, or attitude you’re wanting to convey, but the set font sizes that are available may not. They may be too small or too large. By having the option to modify the sizes, you can tailor every aspect of the look of your site’s copy to your brand’s image.

Adding default widths for content

Content width is a theme feature whereby you can set the default or maximum allowed width (size) for any content in the theme, such as embeds and images added to posts. When you set default widths, WordPress can scale embed codes to specific sizes on the front-end and insert large images without breaking the main content area.

Managing custom CSS (cascading style sheet) properties.

If you’ve spent any time working with CSS, we’re sure you’re asking yourself why you’d even want to write your custom CSS in the radically different JSON format. In a word: flexibility.

Let’s say you’ve settled on a color, forest green, for your site that you really like. With CSS, you’d have to go through and add the color code to all of the places you want to use that color. Not a huge deal, right?

Now let’s say that a few weeks later you find a slightly darker shade of forest green that you’d much rather use. With CSS, you have to go back in and find/replace all of the instances of the “old” forest green color code with the new one.

But, by using theme.json, you’d only have to update the color definition once, in the JSON file, to get it to change across your entire site.

Assign template parts to template part areas

Page templates are files that control how a specific page looks, and they can be used to apply particular page layouts to different pages on your site. In WordPress, there are also template parts, which function as smaller structural sections of a page template.

If you are looking through your theme’s files, you will usually see template parts for things like headers or footers. theme.json allows you to assign template parts to the three available placement areas within a template: General, Header, and Footer.

To Convert or Not to Convert – That is the Question

Now that you’ve gained an understanding of the WordPress theme configuration options available to you courtesy of the theme.json file, we want to touch on one last thing: converting a classic theme to a block theme, and the issues that you should consider when converting.

Block themes in WordPress have a number of benefits, since they have been built to improve both scalability and performance.

• Block themes enhance loading performance by loading the styles only for the  blocks that have been added to a page.
• Block themes are not required to manually enqueue stylesheets for both the front-end and editors.
• theme.json handles all aspects of add_theme_support(), which results in less time noodling around in PHP.
• Accessibility features such as Skip to content, keyboard navigation, and landmarks are generated automatically without adding additional code.
• With a block theme, an end user can edit all parts of their website without touching any code.
• By using the Styles interface, users can customize colors and typography for the website and for any blocks they may use.

However, converting a classic theme to a block theme is not without some risks.

• Converting a classic theme to a block theme may affect child themes that expect a classic theme. Consider the potential impacts — or creating a new project with a new theme name — before converting.
• theme.json requires WordPress version 5.8 or later. Consequently, the support for Internet Explorer 11 was dropped when WordPress 5.8 was released. So, if your classic theme supports IE11 — or you have visitors who use IE11 — converting things over to a block theme potentially impacts your visitor’s experience.

Pro Help is Available!

Although customizing your WordPress themes with options through a theme.json file may be reasonably doable if you’re a beginner or intermediate WordPress developer, perhaps you’re not yet 100% certain it’s a step that you’re comfortable taking alone. Fear not, because when you sign up for DreamHost’s three DreamPress managed WordPress hosting plans, you automatically get access to our elite squad of fully in-house WordPress experts, who are available 24/7 to help you through this and any other components of your development journey!

Do More with DreamPress

DreamPress Plus and Pro users get access to Jetpack Professional (and 200+ premium themes) at no added cost!

Check Out Plans