How to create a child theme of a WordPress block theme

A child theme lets you build on top of an existing theme without touching its files, so your changes stick around when the parent theme is updated. Before the dawn of the Site Editor and block themes, it was the go-to way to customize a WordPress theme, and my answer whenever someone asked me how to modify one of my themes. With block themes, those changes can often go directly into the Site Editor, but there are still good reasons to make a child theme for a block theme.

In this tutorial, we’ll create a child theme of Twenty Twenty-Five, the most recent default theme in WordPress. First the quick way, with a plugin, and then by hand.

Do you need a child theme?

If you just want to change the colors, fonts and templates on your own site, you probably don’t. Changes you make in the Site Editor are saved in the database, not in the theme files, so you don’t have to worry about those changes being overwritten when you install updates for your theme. I’ve received countless emails from exasperated site owners wondering why changes they made directly to one of my classic themes disappeared once they updated it.

A child theme makes sense when:

• You want your changes in files, so you can keep them in version control or move them between sites.
• You want to add PHP to the theme, like registering block styles, without putting it in a plugin.
• You’re building a theme for others on top of an existing one, and want them to be able to install updates for that theme in the future.

The quick way: Create Block Theme

The Create Block Theme plugin is made by the WordPress team, and it can create a child theme for you in a couple of clicks.

1. Install and activate the “Create Block Theme” plugin. You can find it by going to “Plugins” → “Add Plugin”, and searching for it in the search field.
2. Make sure the theme you want to use as a parent theme is active. Then go to “Appearance” → “Create Block Theme” and click “Create a Child of ‘Twenty Twenty-Five’”. If you’re using another theme, the button will have its name instead.
3. Give your child theme a name in “Theme name”. You can also add a description and an author, or do that later in the Site Editor.
4. Click “Create Child Theme”.

The plugin creates the child theme in wp-content/themes and activates it right away. It also moves over any changes you’ve made in the Site Editor, so your site looks the same after the switch. More on why that matters below.

You can do the same thing from the Site Editor: click the wrench icon in the top right to open the Create Block Theme panel, select “Create Theme”, and click “Create Child Theme”.

If you don’t see the “Create Block Theme” menu item, your site doesn’t allow theme files to be edited. That’s the case on some hosts, and for site admins (but not super admins) on a multisite network.

Save your Site Editor changes to the child theme

Once the child theme is active, you can make changes in the Site Editor like you normally would. They’re saved in the database at first, but Create Block Theme can write them to the child theme’s files for you:

1. Make your changes in the Site Editor and save them.
2. Click the wrench icon in the top right to open the Create Block Theme panel, and select “Save Changes to Theme”.
3. Choose what to save. “Save Style Changes” adds your changes from “Styles” to the child theme’s theme.json, and “Save Template Changes” saves the templates and template parts you’ve edited as files in the child theme. Keep “Process Only Modified Templates” checked, so you don’t end up with a copy of every template in the parent theme.
4. Click “Save Changes”.

The plugin also clears the changes from the database, so the files in the child theme are now the only copy. It’s a nice way to work: design in the Site Editor, save the changes to the theme, and keep the files in version control.

The manual way

A child theme only needs one file: a style.css with a “Template” header that points to the folder name of the parent theme.

Create a new folder in wp-content/themes, like twentytwentyfive-child, and add a style.css file to it:

/*
Theme Name: Twenty Twenty-Five Child
Template: twentytwentyfive
Version: 1.0.0
*/

That’s enough for the theme to show up in “Appearance” → “Themes”. Activate it, and your site should look exactly like it did with the parent theme. It’s not very exciting, but it means we can start making changes.

If your site suddenly looks broken, the parent theme is probably at fault. It’s not uncommon for themes to assume that they won’t be used as parent themes, and load assets with get_stylesheet_uri() and get_stylesheet_directory_uri(), which point to the active theme. When a child theme is active, those themes end up looking for their styles and scripts in the child theme folder, where they don’t exist. All themes that aren’t child themes should use get_template_directory_uri() or get_parent_theme_file_uri() instead, which always point to the parent theme, even when a child theme is active.

That’s a bug in the parent theme, so the best solution is to let the theme developer know, so they can fix it for everyone. You can work around it by loading the missing assets from the parent theme yourself, in the child theme’s functions.php, but that could break if the parent theme changes the location of those files in the future. Sort of defeats the purpose of creating a child theme, doesn’t it? Twenty Twenty-Five doesn’t have this problem, obviously.

Change styles with theme.json

In a block theme, theme.json is where the design lives. It defines the color palette, fonts, font sizes and spacing, and the styles for the site and individual blocks. It also controls which settings are available in the editor. The styles you set in the Site Editor (“Styles”) end up in the same format, saved in the database instead of in a file.

Add a theme.json file to the child theme with only the settings and styles you want to change. WordPress merges it with the parent’s theme.json, so there’s no need to copy the whole file. This changes the background color and leaves everything else as is:

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"styles": {
		"color": {
			"background": "#f5f1e8"
		}
	}
}

There’s a lot more you can do with theme.json than change the background color. If you want some ideas, I’ve written tutorials on how to add a variable font and add responsive block styles in theme.json.

Add custom CSS

If you’re as old as me and also remember a time back when “editor” in WordPress parlance meant a TinyMCE box with a row of formatting buttons up top, you might expect WordPress to load the style.css file in our new child theme on the front end automatically. Here’s a gotcha: it doesn’t. Twenty Twenty-Five loads its own stylesheet from the parent theme folder with a piece of PHP, and many other block themes do the same (or don’t load a style.css at all).

The easiest fix is to skip style.css and put your CSS in theme.json instead. CSS for the whole site goes in styles.css, and CSS for a specific block goes in css for that block, under styles.blocks. In the block CSS, you can write the properties directly, and use & to target elements inside the block:

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"styles": {
		"css": ".wp-site-blocks { border-top: 4px solid currentColor; }",
		"blocks": {
			"core/quote": {
				"css": "border-left: 4px solid currentColor; & cite { font-style: normal; }"
			}
		}
	}
}

It’s not a great solution, though. Since we’re editing a JSON file, the CSS has to be written on a single line, which is annoying to write and even worse to read. If you have more than a few lines of CSS, you can load the child theme’s style.css yourself instead. Create a functions.php file in the child theme, and paste this code into it:

<?php
function twentytwentyfive_child_enqueue_styles() {
	wp_enqueue_style( 'twentytwentyfive-child-style', get_stylesheet_uri(), array(), wp_get_theme()->get( 'Version' ) );
}
add_action( 'wp_enqueue_scripts', 'twentytwentyfive_child_enqueue_styles' );

Now you can add CSS in style.css to your heart’s content.

Override templates and template parts

To replace a template or template part from the parent theme, add a file with the same name in the same folder of the child theme. A parts/footer.html file in the child theme replaces the parent’s footer, and a templates/single.html file replaces the parent’s single post template. Everything you don’t override is inherited from the parent.

The easiest way to get the markup for a new template is to edit it in the Site Editor, and then copy the code from the code editor (“Options” → “Code editor”).

What the child theme inherits

Here’s how the different parts of the parent theme carry over to the child theme:

• theme.json: Merged. The child theme’s values win when both themes set the same thing.
• Templates and template parts: Inherited. A file with the same name in the child theme replaces the parent’s.
• style.css: Only the header is required. The CSS isn’t loaded unless you load it yourself.
• functions.php: Both are loaded, the child theme’s first.
• Changes made in the Site Editor: Not inherited.

That last one catches people out. Changes you make in the Site Editor are saved for the theme that’s active when you make them. If you’ve customized the parent theme in the Site Editor and then activate a child theme you’ve made by hand, those changes won’t come along, and your site will look like the unmodified parent theme. They’re not gone, though: switch back to the parent theme, and they’re still there.

Create Block Theme takes care of this for you, by saving the changes into the child theme’s files when it creates it. If you’re doing it by hand, make your changes in the Site Editor after you’ve activated the child theme.