How to create a WordPress child theme

A child theme is a theme that extends another one, called its parent. It includes everything from the parent by default, the design and the features, and adds or replaces only what you put in it. Your changes live in the child's folder. When the parent is updated, its files are replaced and yours are left alone.

When you need one, and when you do not

You do not need a child theme for either of these:

• A few CSS rules. WordPress has its own "Additional CSS" box, and what you put there is kept through theme updates. See how to add custom CSS to WordPress.
• Changes made in the Site Editor on a block theme. The colors, fonts and templates you change there are stored in the database and not in the theme's files, so a theme update does not overwrite them.

You do need one when the change has to be made in a file:

• to change one of the theme's template files, such as the footer
• to add PHP code that belongs with the site's design
• to keep a long stylesheet, or a block theme's settings, in files you can copy and back up

A child theme suits a modest set of changes. WordPress's theme handbook notes that very extensive changes become hard to manage as a child theme and are often better made as a theme of their own.

If you would rather have design and build work done for you, our design and development service sells a small job as developer time by the hour and gives a written quote for a larger one, before any work starts.

Before you start

• Get to the site's files. You need your host's file manager or an SFTP program.
• Take a backup, and make the child theme on a copy of the site if you can. How to set up a WordPress staging site shows how to make one.
• Find the parent theme's folder name. Open wp-content/themes/ and look for your theme's folder. You need the folder's name, not the name shown in the dashboard. Twenty Twenty-Four, for example, is in twentytwentyfour.

Make the child theme

Make sure both stylesheets are loaded

This section is for classic themes. A block theme takes its styles from theme.json, and the step is often not needed there.

WordPress does not load a child theme's style.css of its own accord. The parent theme's code decides which stylesheets go into the page, and the theme handbook describes three cases.

• The parent loads its own stylesheet and the child's. There is nothing to do.
• The parent loads only its own, or none. The site looks right, but rules you add to the child's style.css do nothing.
• The parent loads only the active theme's stylesheet. With the child active, that is the child's nearly empty file, and the site loses its styling.

To see which case you have, look at the site in the child's preview, or with the child active. If the styling is gone, it is the third. If not, open the page's source in your browser and search for the child's folder name followed by /style.css, for example example-child/style.css. If it is there, it is the first case. If it is not, it is the second.

For the second and third cases, create a file named functions.php in the child's folder with the code that matches.

<?php
add_action( 'wp_enqueue_scripts', 'example_child_enqueue_styles', 20 );

function example_child_enqueue_styles() {
	wp_enqueue_style(
		'example-child-style',
		get_stylesheet_uri(),
		array(),
		wp_get_theme()->get( 'Version' )
	);
}

In the first, get_stylesheet_uri() is the address of the active theme's style.css, which is now the child's. The 20 makes the function run after the parent's own loading code, which normally runs at the default of 10. Your stylesheet then comes later in the page, and when a rule of yours and a rule of the parent's are equally specific, the later one wins. The last argument takes the version from the header of style.css. Raise the Version line whenever you change the file, so that browsers fetch the new copy.

In the second, get_parent_theme_file_uri( 'style.css' ) is the address of the parent's stylesheet. WordPress loads the child's functions.php immediately before the parent's, so this function runs first and the parent's stylesheet goes into the page ahead of yours.

Reload the site. Then add a rule below the header in the child's style.css and check that it takes effect.

A child of a block theme

A child of a block theme has the same folder and the same style.css header. What differs is where the changes go.

Styles go in theme.json. A block theme sets its colors, fonts and spacing in a file named theme.json in its main folder. Put a theme.json in the child's folder that holds only what you want to change. WordPress merges the child's file into the parent's, and where both set the same thing the child's value is used.

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

version is the version of the theme.json format. Version 3 works with WordPress 6.6 or later. If the parent's own theme.json gives a lower number, use that number.

Templates are HTML files. They sit in the theme's templates folder, and template parts such as the header and footer in parts. A file with the same name in the same folder of the child replaces the parent's.

Your changes in the Site Editor sit on top of both. WordPress applies its own defaults, then the parent theme, then the child theme, then what you have changed in the Site Editor, and each can override the one before. If a value in the child's theme.json does not show, the same thing may already be set in the Styles panel.

CSS in the child's style.css does nothing in a block theme that loads no stylesheet. Twenty Twenty-Four is one of those. Load the file with the first piece of code in the section above.

What changes when you activate it

WordPress stores some settings under the name of the active theme's folder, and the child has a folder of its own. Look at these after you activate it, or in "Live Preview" before you do.

• Customizer settings. Most settings a theme saves from the Customizer are specific to that theme. Choices you made under the parent may be back at their defaults under the child. Note them down first and set them again.
• Additional CSS. The Customizer keeps this for each theme separately, so the child starts with an empty box. Move the rules into the child's style.css. On a block theme, WordPress's documentation says CSS added in the Styles panel is cleared when you switch themes, so copy it out before you activate.
• Menus and widgets. WordPress passes the positions of your menus on to a theme it activates for the first time. Check them all the same, and the widget areas with them.

To go back, activate the parent theme again. Its Customizer settings are stored under its own folder name, where the child did not change them.

Override a template file

In a classic theme the templates are PHP files, such as header.php, footer.php and single.php. To change one, copy it from the parent's folder into the child's, under the same name and in the same subfolder if it was in one, and edit the copy. WordPress looks in the child's folder before the parent's, so your copy is the one it uses.

Copy only the files you are going to change. A copy in the child no longer receives the parent's later changes to that file. After the parent has been updated, compare the two and carry over what matters.

To undo an override, delete your copy from the child. WordPress goes back to the parent's file.

Add code in functions.php

The child's functions.php does not replace the parent's. Both are loaded, the child's immediately before the parent's. Three things follow from that.

• Do not copy functions from the parent's file into the child's. A function defined twice stops PHP, and the site with it.
• Start your function names with something of your own, as example_child_ does here, so that they cannot collide with a function in the parent or in a plugin.
• Attach your code to a hook, as the example does. When the child's file runs, the parent's has not run yet, so nothing the parent defines exists at that moment.

This example sets the length of automatic excerpts to 30 words. Add the lines to the child's functions.php, below anything already in it. If you are creating the file now, put <?php alone on its first line, above them.

add_filter( 'excerpt_length', 'example_child_excerpt_length', 999 );

function example_child_excerpt_length( $length ) {
	return 30;
}

The 999 makes this run after any length the parent theme sets, because a higher number runs later.

A mistake in this file can stop every page from loading. Edit it through the file manager or SFTP, where you can still reach it when the dashboard is down, and keep a copy of the version that worked. If the site goes blank after an edit, put that copy back, or follow how to fix the white screen of death.