How to create a block child theme in WordPress

Customize your website

Envision this scenario: You’ve just found a near-perfect theme to use on your website. It’s well designed, includes the layouts you want, but you want to change the color palette and limit clients from modifying some areas. Unfortunately, the theme you are using doesn’t let you remove the default colors or lock blocks.

While you could edit the theme’s files directly, all your modifications will be lost when you run updates to the theme. You could add a little custom CSS using a code snippet plugin, but that won’t alter the style options available to logged-in users.

So what can you do? How do you change Global Style available options? For that, you need a block child theme.

What is a WordPress child theme?

According to the WordPress Developer documentation:

A child theme inherits the look and feel of the parent theme and all of its functions, but can be used to make modifications to any part of the theme. In this way, customizations are kept separate from the parent theme’s files. Using a child theme lets you upgrade the parent theme without affecting the customizations you’ve made to your site.

So to make use of a child theme in WordPress, you’ll need to have the parent theme installed as well. Your child theme inherits everything from the parent, with a few variations added.

How to create a child theme

Would you prefer a code option to customize the styling on your site? Like overriding other WordPress themes, using a child theme is the best way to override code. When your theme updates, your child theme code will remain.

In this article, we’re cover the key components of what makes a good WordPress child theme and provide in-depth reading resources.

1. When to use a block child theme

Child themes are a great solution often. However, if you are looking to add just a little bit of CSS code, an entire child theme may be overkill. Consider a plugin like Code Snippets for adding just a bit of customization.

Customizing client sites

When you are building sites for clients, there is some additional customization you might want to offer.

If you want to control the ability for users to insert new blocks, move existing blocks, or delete blocks, you might want to implement block locking. You can learn how to lock blocks and more in this introductory tutorial.

Creating theme variations

In addition to defining what regions of the theme layout clients can modify, you might also want to alter their color palette options, omitting what comes by default with the theme or WordPress and adding in unique options. You can also define gradients and duotone options that should be available in your theme as well.

2. Pick a good WordPress theme

Not all themes are created alike. In addition to what you see in the theme design, selecting a parent theme involves additional factors like the frequency of updates, quality of support, documentation, and reputation of the theme developer. Learn more in How to use WordPress themes to build a website.

3. Create a testing environment

By now you’ve picked out the parent theme, gathered brand assets, and decided what settings you would like to override. Next, you’ll need to set up a testing environment.

If you’re using a managed WordPress hosting provider like GoDaddy’s Managed WordPress Hosting, you can use your one-click staging site as a development environment. If you’re using something like cPanel or VPS for hosting, you can set up a separate WordPress installation and clone or copy your existing site over to the new installation.

If you’re not applying the child theme to an existing site, or if you’d rather build from scratch, you can create a local WordPress development environment on your computer using a tool like MAMP or DesktopServer from ServerPress.

4. Create your theme directory

First you’ll need to install the parent theme. Then, using an FTP client, connect to your development environment and navigate to where your WordPress files are located.

You’re looking for the following folder:

/wp-content/themes/

That’s where you can find all of your installed WordPress themes. Each theme has its own folder or directory that contains all of the theme’s files. You’re going to add a new directory to the list, which will hold your child theme. You’ll end up with something like:

/wp-content/themes/your-child-theme/

5. Create your theme files

For our example, we’ll assume we’re using the Twenty Twenty Two theme. You’ll need to have that theme installed for the child theme to refer back to it.

Within your new child theme directory folder, you’re going to create two new files:

style.css
theme.json

Both of these files serve a specific purpose. The style.css file is used to provide WordPress with information about the theme, like the name, author, tags and parent theme ID.

The theme.json file is used to define the many settings in Global Styles and more. Learn more about theme.json from the developer handbook.

In previous Classic themes, the functions.php file was necessary in child themes. Block child themes do not require these step.

Style.css

What belongs in your style.css file? The developer documentation says:

Your stylesheet must contain the below required header comment at the very top of the file. This tells WordPress basic info about the theme, including the fact that it is a child theme with a particular parent.

You’ll need to include the boilerplate in style.css file containing your header information. The Template Name: corresponds to the folder (directory) name of the parent theme you’re building on top of. The Text Domain: name is unique to your WordPress child theme.

Below is an example of a child theme using Twenty Twenty Two:

/*
Theme Name: Twenty Twenty-Two Child
Theme URI: https://example.com/
Author: Your name
Author URI: https://example.com/
Description: Twenty Twenty Two Child Theme
Requires at least: 5.8
Tested up to: 5.9
Requires PHP: 5.6
Version: 0.1
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: twentytwentytwo-child
Template: twentytwentytwo
Tags: custom-colors, custom-menu, custom-logo, editor-style, featured-images, full-site-editing, block-patterns

Twenty Twenty-Two Child WordPress Theme, (C) 2021 WordPress.org
Twenty Twenty-Two Child is distributed under the terms of the GNU GPL.
*/

Theme.json

See the developer documentation for a deeper dive into theme.json. Let’s take a look at the Twenty Twenty Two theme.json file:

{
	"version": 2,
	"settings": {},
	"styles": {},
	"customTemplates": {},
	"templateParts": {}
}

Within each of these are further styles available to you. For example, in the style’s area, Twenty Twenty Two uses:

{
	"settings": {
		"appearanceTools": true,
		"color": {
		"duotone": [
			{
				"colors": [
				"#000000",
				"#ffffff"
		],
	"slug": "foreground-and-background",
	"name": "Foreground and background"
}

Need help making a theme.json file? Check out the themegen.app for a guide creating many of the choices for your theme.json file.

6. Customizing your block child theme

While you might create your theme.json file easily and append it to your theme, there are a few other choices left to make. Child themes and even block themes are a new area for WordPress. The Site Editor clearly has a beta label on it at the time of this post. You’ll want to refer back to see what does and does not work yet in child themes, such as template parts.

The state of child themes

Additionally, you may find settings that Global Styles and theme.json do not yet support. If you are adding additional CSS, such as a group block border with a box-shadow, you might want to add that to your style.css file.

.has-primary-border-color {
    box-shadow: .1rem .1rem .05rem #647BAF ;
}

7. Test your child theme

Once you feel that your site looks good in your current development environment, it’s time to give it a test before uploading to a live site.

  • Test in various browser sizes, such as mobile viewports
  • Test in different browsers or use a tool like BrowserStack
  • Review accessibility standards. Get started with WebAim

8. Prepare to upload your block child theme

If you have been developing on a staging site, your files are exactly where they need to be. You can visit your hosting options to push the staging site to live. If you’ve been creating files on a local developer environment, it’s time to zip style.css and theme.json files together as one zip file and upload to your site.

Recap to creating your block child theme

  1. Decide of you need a block child theme
  2. Pick a parent theme
  3. Configure your testing environment
  4. Create your theme directory
  5. Create your theme files
  6. Customize your block child theme
  7. Test your child theme
  8. Upload the them to live site

Like Classic themes in WordPress, Block themes still need a place to store customizations that won’t be overwritten when the parent theme receives an update. Creating a block child theme enables you to add, lock, and omit options available to other users on the site.