Full Site Editing

In 2021 I wrote a widely spread blog post called “The state of child themes” about the problems I encountered while trying to create block child themes. The update is long overdue, but it is finally here: The good news is, block child themes are now fully supported!

To follow along with this article, you need basic knowledge of child themes, block theme templates, and the Site Editor. It assumes you are familiar with theme.json style variations, settings, and styles.

Written by:

Carolina Nymark

Level: Developer, Intermediate

Estimated reading time: 9 minutes

Last updated

August 3, 2024

Do I still need a child theme?

Child themes are traditionally used to make minor customizations to a theme and protect those changes from being replaced by a theme update.

Block themes are highly customizable and essentially solve these problems. Themes that include global style variations can offer many designs in one theme.
You can also use the Site Editor to make structural changes to templates and add new templates without code. When you edit your site in the Site Editor, WordPress saves your changes to the database, so you don’t need to worry about theme updates removing your changes. For these reasons, the need to create a child theme is much lower than a few years ago.

– Whether you need a child theme depends on the changes you want to make.
If you change theme.json, HTML, CSS, PHP, or JavaScript files directly, you still need to create a child theme because these files are not protected when you install a theme update.
There are also settings and styles in theme.json that you can not remove through the WordPress interface. In this case, you also want to create a child theme and add your custom theme.json.

What types of child themes can I create?

You can create any child theme for any kind of parent theme. You can mix two block themes or hybrid themes; you can use a PHP-based child theme for a parent block theme, a block child theme for a PHP-based theme, and so on. No matter what type of child theme you want to create, you can use it to extend or override the parent theme:

• The child theme inherits functions, filters, templates, template parts, block patterns, and theme.json from the parent theme.
• It overrides the parent theme by duplicating the parent theme files or theme.json features.
• It extends the parent theme by including new files and theme.json features not included in the parent theme.

Why should I create a block child theme for a classic theme?

• You may want to explore how you can take advantage of the presets in theme.json before updating your existing theme.
• You may want to offer your users custom templates with template editing and the Site Editor without affecting your existing theme.

Parent and child theme templates

When you want to override template files or share them across themes, remember these two rules:

1. WordPress checks for files in the child theme before loading parent theme files.
2. If a theme has a templates/index.html file, WordPress will check for HTML templates inside the templates folder before loading PHP template files from the root directory.

The loading order for files in the template hierarchy for hybrid themes and block themes is as follows:

1. Child theme .html file
2. Child theme .php file
3. Parent .html file
4. Parent .php file

If the parent theme is a hybrid theme:

index.php
single.php
page.php
header.php
/templates/
   404.html
/parts/
   header.html

And the child theme includes these files:

/templates/
   index.html
   single.html
/parts/
   header.html

WordPress will use the following files:

page.php
header.php, if we assume it is included from page.php.
/templates/
   index.html
   single.html
   404.html
/parts/
   header.html from the child theme

And if you create a new page post type template in the Site Editor, it overrides page.php.

Will I lose my template changes if the theme developer updates the theme?

When the parent theme is updated, only the templates and parts that you have not saved will be updated:

• You will not lose your updates if you have copied the templates and template parts to your child theme before making changes. WordPress will use the files from your child theme.
• If you have not copied the templates but saved changes to the templates in the Site Editor, you will not lose those changes.

If you have saved changes in the Site Editor but you want to use the updated template from the parent theme, you must first reset your customization.

What happens if the parent theme adds new templates? Can I use them?

If the parent theme adds new templates, they will be available if you do not already have a template with the same name.

What happens if the parent theme removes templates?

If you have not copied the templates to the child theme or saved them in the Site Editor, the templates will no longer be available. Existing content that uses that template will fall back to the closest template and use that template instead.

Can I remove a parent theme template from a child theme?

No. You can replace the template, but there is no known way to remove a parent theme template. Templates and template parts can be listed in theme.json, but removing them from the theme.json in the child theme does not disable them.

Using theme.json in child themes

When both the parent theme and the child theme include theme.json:

• The child theme inherits all features from the parent theme.json.
• The child theme.json overrides the parent by duplicating styles and settings.

Settings and styles in the child theme.json replace the equivalent in the parent; it is not possible to make partial edits: If the child theme.json includes a color palette, this completely replaces the parent’s color palette. So even if you want to replace a single color, you must copy the whole palette from theme.json.

Will I lose my styles and settings if the parent theme.json is updated?

It depends. There are two ways to protect your styles: By editing and saving global styles in the Site Editor and by including a theme.json in the child theme.

There are edge cases when an update to a parent theme.json file is still applied to your website, and that is when the parent adds a new style or setting that you have not overwritten in your theme.json. For example, if neither the parent nor the child included custom gradients, but the parent adds custom gradients in an update, then the child theme will inherit the gradients.

Child themes inherit theme.json style variations

Similarly, a child theme inherits the parent theme style variations. There is no way for a child theme to remove a parent theme style variation, only override it. For example, to override the
“Pitch” style variation in a Twenty Twenty-Three child theme, you would include your own styles/pitch.json file.

How to remove parent theme features

Block patterns

As I mentioned at the beginning of the article, child themes inherit block patterns registered in the parent theme. The child theme can deregister a block pattern with the unregister_block_pattern() function.

Custom block styles

Child themes inherit custom block styles from the parent (A custom block style is a style that can be selected in the user interface. An example of a block style is the “rounded image”). You can deregister custom block styles in the child theme with the unregister_block_style() function.

Partial JSON files

If the parent theme includes a style variation, section style or preset in the styles folder, the child theme can remove override it by adding an empty file with the same name in its own styles folder.

Child theme code examples

So far, I have written about child themes in theory. I want to add some code examples and describe typical use cases in this section. All examples use Twenty Twenty-Three as the parent theme.

How to create a basic child theme

Child themes require a theme folder and a style.css file with a Template parameter in the file header. Of course, you will also need to add your customizations.

1. If your child theme’s name is FSE child, create a new folder inside wp-content/themes/ called fse-child.
2. Inside your child theme folder, create a new style.css file with a minimal file header.
   The Template parameter value is the slug of the parent theme:

/*
Theme Name: FSE child
Template: twentytwentythree
*/

This is the absolute minimum required for activating the theme. Except for Template, child themes use the same style.css file header as parent themes.

Loading the child theme’s style.css file

Not all parent themes are built to load the child theme’s style.css file automatically. For example, Twenty Twenty-Three does not enqueue any CSS files.

If you want to add custom CSS using the child theme’s style.css file, you should check if the file is already loaded. If it is not, you need to add a functions.php file to the root folder of the child theme.
The next step is to create a new function in functions.php that enqueues the stylesheet:

function fse_child_styles() {
	wp_enqueue_style( 'fse-child-style', get_stylesheet_uri() );
}
add_action( 'wp_enqueue_scripts', 'fse_child_styles' );

The Theme Developer Handbook explains how to load both the parent and child theme stylesheets.

Overriding settings and colors with theme.json

Removing default padding

One of the most frequently asked questions about Twenty Twenty-Three is how to remove the site-wide top and bottom padding. You can do this in the Layout section in the Site Editor, but I want to show you how to do it in your child theme:

1. First, create a theme.json file in the root folder of your child theme.
2. Next, add the following code to theme.json:

{
	"version": 2,
	"styles": {
		"spacing": {
			"padding": {
				"top": "0",
				"bottom": "0"
			}
		}
	}
}

The version number tells the parser in WordPress that this theme.json format supports padding. Without the version number, the change will not work.
In these examples, the child theme is using the same version as the parent theme.

By only changing the top and bottom padding, the child theme inherits all other settings and styles from the parent theme.json. -Including the parent theme’s left and right padding.

Changing the color palette

Let’s look at another example: How to change the color palette. Replace the content of your theme.json with the following:

{
	"version": 2,
	"settings": {
		"color": {
			"palette": [
				{
					"color": "#ffffff",
					"name": "Base",
					"slug": "base"
				},
				{
					"color": "#000000",
					"name": "Contrast",
					"slug": "contrast"
				},
				{
					"color": "#6d93f4",
					"name": "Primary",
					"slug": "primary"
				},
				{
					"color": "#345099",
					"name": "Secondary",
					"slug": "secondary"
				},
				{
					"color": "#F6F6F6",
					"name": "Tertiary",
					"slug": "tertiary"
				}
			
			]
		}
	}
}

This palette only changes the two green colors in Twenty Twenty-Three (primary and secondary) to blue. Leaving all other colors and features untouched.
WordPress will update all blocks that use the palette colors to show the new blue colors.

Enabling or disabling features

Twenty Twenty-Three disables a feature for the paragraph block: The drop cap. There is no setting in the user interface where you can re-enable it, but you can solve it with your child theme:

Replace the content in the theme.json example file you created earlier with the following code:

{
	"version": 2,
	"settings": {
		"typography": {
			"dropCap": true
		}
	}
}

The drop cap feature should now be available in the block editor:

Useful resources

Child theme related lessons on learn.wordpress.org

Courtney Robertson: How to create a block child theme in WordPress