WordPress child themes: why you need one and how to build it

Imagine a site where you have been editing theme files yourself for a long time: a line in header.php, a small change in footer.php, a few CSS rules. Then a notice says the theme has a new version. You click "Update" and all your changes vanish at once. WordPress updates a theme by replacing its whole folder.

The standard solution is a child theme. In this article we look at what a child theme is, when you need one, and how to build it in a few minutes.

How does a child theme work?#

A child theme is a small folder that points to another theme, the parent. WordPress looks for each file in the child theme first, and reads it from the parent if it is not found. The result:

• A file you put in the child replaces the same-named file in the parent.
• A file you do not provide comes from the parent.
• You can safely update the parent; the child folder is left untouched.

When do you need a child theme?#

One important point: any code that is not about appearance, such as registering a custom post type or a tracking snippet, does not belong in a theme. If you switch themes, all of it stops working. Put that code in a plugin; see building a WordPress plugin from scratch.

Build a child theme, step by step#

Suppose the parent theme folder is named my-parent. Check the exact folder name, including letter case, in wp-content/themes.

1. Create a new folder in wp-content/themes, for example my-parent-child.
2. Inside it, create style.css with the header below.
3. Create functions.php to load the styles.
4. Activate the child theme under Appearance > Themes.

The style.css file#

/*
Theme Name:   My Parent Child
Template:     my-parent
Version:      1.0.0
Description:  Child theme for customization
Text Domain:  my-parent-child
*/

/* Your custom CSS goes below this line */

The most important line is Template. Its value must be exactly the parent theme's folder name, not its display name. If you get it wrong, WordPress says the parent theme was not found.

The functions.php file#

In classic themes the parent stylesheet is not loaded automatically, so you have to enqueue it. The right way is wp_enqueue_style, not @import in CSS, which is slow and no longer recommended:

<?php
add_action( 'wp_enqueue_scripts', 'mpc_enqueue_styles' );

function mpc_enqueue_styles() {
	$parent_version = wp_get_theme( get_template() )->get( 'Version' );
	$child_version  = wp_get_theme()->get( 'Version' );

	wp_enqueue_style(
		'my-parent-style',
		get_template_directory_uri() . '/style.css',
		array(),
		$parent_version
	);

	wp_enqueue_style(
		'my-parent-child-style',
		get_stylesheet_uri(),
		array( 'my-parent-style' ),
		$child_version
	);
}

Remember two functions: get_template_directory_uri() always points to the parent, and get_stylesheet_directory_uri() points to the active theme, which is the child. Passing the version as the last parameter means the browser cache is refreshed whenever the version changes.

If the parent theme adds its styles in a non-standard way or from another file, the code above may be unnecessary or insufficient. Check that theme's documentation.

How do you override parent files?#

Copy the parent file you want to change into the child theme, using the same name and the same path, and edit it there. For example footer.php or template-parts/content.php. From then on WordPress reads the child's version.

functions.php is different from the other files: the child file does not replace the parent's. Both are loaded, the child first and then the parent. So only add to the child's file, and do not copy the whole parent file; otherwise functions get declared twice and the site throws a fatal error.

If the parent defines a function wrapped in if ( ! function_exists(...) ), the theme author has allowed you to override it in the child. If not, instead of copying, it is better to use the hooks (actions and filters) the theme provides.

Child themes for block themes#

Block themes have child themes too, and they are simpler: only style.css with the same header is required, and in most cases you do not need functions.php to load the parent styles. You override color and typography settings with the child's theme.json file. If you work with a block theme, also read block themes and the Site Editor. Changes you save from the Site Editor are stored separately in the database and are not lost when the theme updates.

Common mistakes#

• Wrong name in Template: it must be the parent folder's name.
• Missing parent styles: the site looks unstyled.
• Copying the whole functions.php: a "cannot redeclare function" error.
• Editing the parent directly "just once": it is lost at the first update.
• Expecting the child to fix a bad parent: if the parent theme is slow or insecure, a child does not help; see choosing a WordPress theme.

A maintenance note#

A child theme needs maintenance too. After each major parent update, compare the files you have overridden with the parent's new versions; the parent may have changed the structure of those files. For this reason, keep overrides to a minimum: the fewer files you copy, the easier maintenance is.

Summary#

• Editing your current theme directly is lost on update; a child theme is the safe way.
• A child theme needs at least style.css with a correct Template line.
• In classic themes, load the parent style with wp_enqueue_style, not @import.
• Override parent files by copying a same-named file into the child; functions.php is the exception.
• Put code unrelated to appearance in a plugin.
• Keep overrides few and compare them after parent updates.