How to Create WordPress Child Themes in WordPress (Extended Guide)

You’ve been running your WordPress site for a while and it’s been doing what you need it to. But now, you decide you need to customize it.

Or maybe you’re creating your site with a theme you’ve downloaded from the theme directory or one you’ve bought, and you realize it doesn’t work in exactly the way you need it to.

What do you do, then?

You can either find a plugin that will provide the customization you need or switch to a new theme. But what if you’re happy with your current theme and can’t find a plugin that adds what you need in terms of functionality?

Answer: you’ll need to customize your theme. And best practices say: you do that via (WordPress) child themes.

In this post, I’ll show you exactly how to create a child theme in WordPress, how to use it to customize your site, and how child themes work. I’ll also explain the concept of parent themes and describe how the parent theme on your site interacts with a child theme:

Before we dive into creating a child theme, let’s identify the 3 methods you can use to customize your WordPress site.

Methods of Customizing WordPress

Customizing a theme comes with risks. If you edit the code in a third-party theme (which is one you bought off of a marketplace for example), then when you next update the theme, all your changes will be lost. Meaning that not only does your site revert back to the way it was, but all of your work is wasted.

There are three ways to customize your WordPress site:

Let’s take a look at each of these in turn.

Editing Your Theme

If your site is running a custom WordPress theme, which means that it has been developed specifically for your site, you have the option of safely editing it because there isn’t a risk of losing your customizations next time the theme is updated.

Instead, if you or your developer make changes to the theme in the future, it’s the customized version of the theme you’ll be editing, and not the original version before those changes.

That doesn’t mean that editing your theme doesn’t come without risk. If you aren’t experienced at coding themes, it may still be safer to create a child theme (we’ll see how in a minute). This is something I do: I have one base theme that I use on all my sites, with standard layout, hooks, and functions, and then I customize it on each site with a child theme.

If you do edit your theme directly, make sure you keep a backup of the original theme, don’t edit the theme in the live site (use a development or staging site instead), and use version control to keep track of your changes.

And if you’re using a third party theme, you should never edit it directly. Instead, use a plugin or create a child theme.

Adding a Plugin

The second option for customizing a WordPress theme is to install or code a plugin.

If the customizations you want to make are functional instead of design-related, a plugin is a more appropriate way to do this. So if you want to add extra code, it may be better to create a plugin instead.

Plugins don’t have to be large or complex: if you need to add extra code to the functions.php file in your theme, create a simple plugin to add a few lines of code to your site. A good example is registering a custom post type.

It may be tempting to add code to your theme’s functions.php, but adding a post type is a functional change to your site, not a design one. If you were to switch themes in the future, you wouldn’t want to lose those post types and all the posts you’ve created using them. That’s why you should install or create a plugin instead.

Sometimes you’ll be able to find an existing plugin that does what you need, but sometimes you may need to code the plugin yourself.

If in doubt about whether you should create a plugin or customize your theme (or child theme), ask yourself this: if I wanted to change the design of my site in future and installed a new WordPress theme, would I want this change to remain? If the answer is yes, that means the change is functional and not aesthetic, and it should go in a plugin.

Creating a Child Theme

The third option for customizing WordPress theme is to create a child theme.

Here are some scenarios in which you’d use a child theme:

• You want to make changes to the design of the site, not the functionality.
• Your site is running a third-party theme or a theme you want to use again in its current state.
• You don’t want to directly edit your existing theme in case it causes problems (maybe you’re not an experienced theme developer).
• Your site is running a theme designed to be a parent theme, such as a framework theme. These are themes with lots of customization options such as hooks, designed for you to add to with your own child theme.

Child themes are therefore an effective and safe way to add customizations to your site. So let’s take a look at them in more depth.

What Is a WordPress Child Theme?

So, what exactly is a child theme in WordPress? How does it work?

A child theme is a theme that works in tandem with another theme, which is referred to as the parent theme.

It contains some specific instructions to tell WordPress that this is a child theme and what the parent theme is. WordPress then uses the code from the parent theme in most instances but will override this with code from the child theme (if necessary). If you come across a site using a child theme that you like, use our theme detector tool to find out what the parent theme is.

The Files in a WordPress Child Theme

Every WordPress child theme must have two files as a minimum: a stylesheet and a functions file. The stylesheet will contain commented out text at the top telling WordPress that this is a child theme and what the parent theme is. The functions file will include a function that enqueues the stylesheet from the parent theme.

Note: You may come across guides that tell you to call the parent theme stylesheet from the child theme’s stylesheet. This is no longer the correct way to do it, and you should use enqueuing in the functions file instead. I’ll show you how to do this shortly.

Your child theme doesn’t have to include any other files. Unlike the parent theme, it doesn’t need an index.php file as the fallback if there aren’t any more specific files in the theme. This is because if a template file doesn’t exist in the child theme, WordPress will use the file from the parent theme.

So, depending on what you want your child theme to do, you will either add extra code to the stylesheet, to the functions file, or you’ll create extra files in the child theme to override the parent theme. These might include one or more of:

• Template files to override the same file from the parent theme, such as page.php when you want to customize the display of static pages.
• Template parts such as header.php or footer.php when you want to customize these parts of the site design.
• Extra template parts that you call from template files in your child theme. So if you wanted to customize the header when static pages are being displayed, you would create a file in your child theme called header-page.php, and a template file called page.php, which would override page.php from the parent theme. This template file would be identical to the one in the parent theme except for the call for the header file, which would call header-page.php instead of header.php.
• Extra include files for functionality. If you want to add a lot of functional code and organize it, you might create include files for each set of functions and then call them in your child theme’s functions.php file. So for example, if you wanted to add extra Customizer options, you might add an include file called customizer.php in your child theme and then call that file from the functions file in your child theme.

But if you do add extra files and functions, how does WordPress know which to use? The ones from the parent theme or the ones from the child theme? That’s what we’ll come to next.

How WordPress Chooses Template Files

The way that WordPress chooses template files from your theme when displaying content on your site is by reference to the template hierarchy.

WordPress uses this hierarchy to work through the template files in your theme and find the right one to use when displaying a given kind of content. It’ll start at the top (on the left-hand side in the image above) and look for each file for the given content type in turn. When it finds a file that will display that content, it will use it.

Imagine your theme has an archive.php file and a category.php file but no tag.php file. When displaying a category archive, WordPress will use category.php as it’s more specific to the content type. When displaying a tag archive, it’ll use archive.php instead.

If WordPress doesn’t find a template file for the given content type, it’ll default to the catch-all index.php file, which is why every standalone theme (i.e. not a child theme) has to have an index.php file.

The same applies for single posts and pages. Let’s say your theme has a singular.php file, which is the catch-all for single posts of any post type (including pages and custom post types). It also has a page.php file. When displaying a single page, it’ll use page.php. When displaying a post, it’ll use singular.php. And if you register a custom post type and don’t add a template file for that post type, it’ll use singular.php again.

When you use a child theme, WordPress still uses the template hierarchy to decide which file to use when outputting content on your site. It looks at the files in both the parent and child themes and uses the first file it comes across.

So imagine your child theme has singular.php and post.php, and your parent theme has page.php and index.php. When outputting a single post, WordPress will use post.php from the child theme. When outputting a page, it’ll use page.php from the parent theme. And when outputting a single post of a custom post type, it’ll use singular.php from the child theme.

But what if both your child and parent themes have instances of the same file?

Let’s imagine you add a page.php file to the child theme in the previous example. Because that theme is in the child theme, it overrides the same file from the parent theme. So when displaying a single page, WordPress would use the new page.php file from the child theme.

This is why creating a child theme lets you customize the parent theme. If you add a copy of a template file from your parent theme to your child theme and then edit it to include the customizations you want to make, WordPress will use this new template file instead of the one from the parent theme. Which means your customizations will be used when displaying content, without you having edited the parent theme. Nice!

How WordPress Runs Functions from Parent and Child Themes

What if you want to make customizations not to the template files in your theme, but to the functions?

You can do this too. First, you need to satisfy yourself that the right way to do this is via a child theme and not a plugin. One example might be where you want to edit a function that’s already in the parent theme, for example, the function that outputs the colophon in the footer.

You then add the new function(s) to the functions file in your child theme, or to an include file that you call from the functions file.

To ensure that your new function overrides functionality from your parent theme, you need to understand how to override functions. There are three ways of doing this:

• By writing a new function with the same name as a pluggable function in your parent theme.
• By unhooking the function in your parent theme from the hook it was attached to and then writing a new function to replace it.
• By writing a new function with higher priority than the original function and calling it via the same hook, meaning that it’s called after the original function and can, therefore, override or augment it.

We’ll examine how you do all of these later in this post. But first, let’s look at the scenarios when you would and wouldn’t use a child theme.

When To Use a Child Theme in WordPress (Advantages)

You now know what child themes are and how you can use them to override the template files or functions in your parent theme.

As a short recap, you should use a child theme if you’re running a theme on your site and you want to do one or more of the following:

• Edit one or more of the template files.
• Add extra functions that are related to display and not functionality.
• Override one or more functions from the parent theme.
• Add extra template file(s).

Some advantages include:

• Easy extending and customization: As is obvious, a child theme extends the functionality of its parent theme. You already have a readymade template at your service in the form of a parent theme, and all you need to do is to create a separate style.css file for your child theme, and add the customization tweaks as per your needs.
• Hassle-free updates: As WordPress evolves, themes and plugins need to be updated ever so often. If you make customization tweaks and changes to your primary theme, you may end up losing all your changes if you ever update the theme. Thus, it is advisable to make such changes to a child theme, such that even if you are ever required to update the parent theme, you have no fear of losing your changes.

What about when you wouldn’t use a child theme?

When Not To Use a WordPress Child Theme (Disadvantages)

There are times you wouldn’t use a child theme and should use a different method of customizing your site. These are:

• If your theme is one you developed yourself (or someone else wrote for you) and don’t need to use it anywhere else. Just edit the theme, making sure you use version control.
• If the customizations you want to make are functional, e.g. adding a custom post type, and you would want to keep them if you change themes in the future. Use a plugin instead.

Some disadvantages include:

• Picking the ideal parent theme: Not all themes act as good parents! Certain WordPress themes, for example, may not be updated regularly and thus tend to lack the latest functionality. Similarly, not all WordPress themes are created with child themes in mind and as such, may serve as bad candidates for parent themes. You need to pick the perfect parent theme in order to properly extend it and make it work as a foundation for your child themes.
• Customization efforts: A child theme basically seeks to extend and customize an existing template design. Thus, if you have already created a website around your parent theme, you may need to reconsider customization of elements such as menus, theme options, sidebars, header, etc. when moving to a child theme.

Now that you know when (and when not) to use a child theme, it’s time to get to work and learn how to create a child theme in WordPress.

How to Create a WordPress Child Theme

Setting up a basic child theme in WordPress involves creating two files: the stylesheet and the functions file. Let’s take a look at them both.

The Stylesheet

Before you create your file, you need to create a folder to hold your theme. This goes in the wp-content/themes file of your WordPress installation.

Remember: don’t do this in your live site. Add the code to a development site first and then test it on your staging site. Once you’re happy with it, you can transfer it to your live site. All Kinsta hosting plans include staging.

In the folder for your new theme, create a file called style.css. Add the following to it:

/*
Theme Name:  My Child Theme. Child for Twenty Nineteen.
Theme URI:  https://rachelmccollin.com
Description:  Theme to support tutsplus tutorial. Child theme for the Twenty Nineteen theme.
Author:  Rachel McCollin
Textdomain:  mccollin
Author URI:  https://rachelmccollin.com/
Template:  twentynineteen
Version:  1.0
License:  GNU General Public License v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html                 
*/

This text is commented out. It’s not code that runs anything on your site or provides any functionality. Instead, it tells WordPress about the theme. You need text like this in every theme, otherwise, WordPress can’t recognize it as a theme.

Let’s work through each of those lines to identify what they do:

• Theme Name: The unique name for the theme.
• Theme URI: Where users can find the code or documentation for the theme.
• Description: Descriptive text to help users understand what the theme does..
• Author: your name
• Textdomain: this is used for internationalization. Use the text domain as the second parameter in any internationalization functions.
• Author URI: The author’s website.
• Template: The folder where the parent theme is stored. Use the folder name and not the theme name. Without this line, your theme won’t work as a child theme.
• Version: The version number
• License: The license, which must be GNU. https://kinsta.com/blog/wordpress-child-theme/
• License URI: The link to information on the license.

The most important line for a child theme is the Template: line. Without this, the theme won’t work as a child theme. Only child themes will include this line.

Add this to your theme’s stylesheet, editing it to add your own details instead of mine. You’ll need to edit the Template: line to add the folder your existing theme is stored in, as that will be your parent theme.

Now save the file. If you were to look at the theme details screen in your site now, you’d see all of this displayed:

This doesn’t look brilliant because there’s no screengrab. This is an image that gives an idea of how the theme looks. Unless your theme will look very different from the parent theme, just copy the screenshot.png file from your parent theme to your child theme.

The Functions File

The next step is to add a functions file to your child theme. You need this so that you can enqueue the stylesheet from the parent theme. Without it, your site would have no styling at all, and would look something like this:

Not good, I’m sure you’ll agree! So let’s add the styling to make it look as it should.

In your child theme folder, add a file called functions.php. Open it and add this code:

<?php
/* enqueue script for parent theme stylesheeet */        
function childtheme_parent_styles() {
 
 // enqueue style
 wp_enqueue_style( 'parent', get_template_directory_uri().'/style.css' );                       
}
add_action( 'wp_enqueue_scripts', 'childtheme_parent_styles');

That uses the wp_enqueue_style() function to enqueue the stylesheet from the parent theme, with the get_template_directory_uri() function locating where that file is stored. The function is inside a function I’ve created called kinsta_parent_styles(), which is hooked to the wp_enqueue_scripts hook.

You may be wondering why it uses a function called wp_enqueue_scripts and not wp_enqueue_styles. This is because wp_enqueue_scripts is used for both scripts and styles and there is no such hook as wp_enqueue_styles.

Feel free to edit my code to add your own prefix to the name of your function. I’ve used “childtheme” as my prefix to ensure my function doesn’t clash with any other functions from the parent theme or from any plugins.

Now save your file.

How to Activate Your WordPress Child Theme

Once your child theme is ready, you need to activate it. If you’re worried that activating the child theme will turn off the parent theme, don’t fret: WordPress will know to use the files from the parent theme unless you add new files to the child theme that override them. So far, you haven’t added any extra files or functions to the child theme, so your site will work in exactly the same way as it would with the parent theme activated.

Remember: Do this on your development or staging site first. Don’t activate your child theme on your live site until you’ve tested it.

In the WordPress admin, go to Appearance > Themes. You’ll find your child theme listed amongst the themes installed on your site.

Hover over the theme and click the Activate button. This will activate your child theme. Now when you visit your live site, it will look the same as it did before:

It looks the same because you haven’t added any customizations yet. But you now have a working child theme. Well done!

How to Customize your Child Theme in WordPress

Now that you have a working child theme for your WordPress site, it’s time to add your customizations. Here I’ll show you how you add template files to override the ones on your parent theme, how to add styling to your child theme, and how to add new functions.

Let’s start with template files.

How to Add Template Files to Your WordPress Child Theme

We’ve already looked at how WordPress chooses which template file to use when displaying content on your site. There are two things to remember:

• WordPress will use the file that comes first in the hierarchy, either from the child or the parent theme.
• If a template file (or a template part such as header.php) with the same name exists in both the parent and child themes, WordPress will use the one from the child theme.

To add customizations, I find it easier to start by making a copy of the relevant file from the parent theme, adding that to the child theme, and then editing it.

This applies whether the file in your child theme will be the same named file as in the parent theme, or if it will be a new file for displaying a different content type, or one that’s higher in the hierarchy.

So if I’m adding a new version of page.php to my child theme, which will override page.php in my parent theme, I will copy page.php from my parent theme to my child theme and then edit it. Make sure you copy the file: don’t move it, as you don’t want to make any changes to the parent theme.

And if I want a custom page template in my child theme, for example, I will copy page.php to my child theme, rename it, and then edit that.

This way, you can ensure all the aspects of the file that you don’t need to customize will still work correctly. The same applies to template parts.

How to Add Styling to Your WordPress Child Theme

You can also add styling to your child theme’s style.css file, which will augment or override the styling in your parent theme’s stylesheet.

WordPress will call the stylesheet from the parent theme first, and then the stylesheet from the child theme. This means if you add styling to the child theme that targets the same element(s) as styling in the parent theme, it will override the styling from the parent theme as long as you use the same selector(s).

So imagine you want to change the color of the site title. In the parent theme, this might be styled something like this:

h1.site-title {
 color: #000;
}

To override this in your child theme, you would add this:

h1.site-title {
 color: #303030;
}

As the browser will come across this after the styling in the parent theme, it will override that and be used instead.

How to Add Functions to Your WordPress Child Theme

So, you’ve created a child theme in WordPress not because you want to edit any of the template files, but because you want to add extra functionality or override one or more of the functions in the parent theme.

Writing functions in your child theme is a little more complicated than adding template files, but it is possible.

If you want to add a new function that doesn’t interact with any of the functions in your parent theme, you can just go ahead and do that. Just add the function to the functions.php file in your child theme, hook it to the relevant action or filter hook, and you’re good to go.

But if you plan to override or edit a function in the parent theme, you need to understand the methods you can use to do this. There are three ways you can override a parent theme function in your child theme:

• If the theme in the parent theme is pluggable, you simply write another function in your child theme with the same name and WordPress will run that function instead of the one in the parent theme.
• If you want to stop the function in the parent theme from running altogether, you can write a function in your child theme that unhooks it from the hook it’s attached to.
• If you want to augment a function, you can add another function (with a different name) in your child theme and make sure it runs after the one in the parent theme.

Let’s take a closer look at how you do each.

Overriding a Pluggable Function

A pluggable function is identified by the conditional check that is wrapped around it. This checks if there’s another function with the same name that’s already been fired. If so, it doesn’t run the function.

WordPress will fire functions from your child theme before those from the parent theme. If it comes across a pluggable function in the parent theme and you’ve added a function to your child theme with the same name, the pluggable function won’t run.

An example is the function that outputs the colophon in the Storefront theme for WooCommerce sites. Here’s the function without its contents:

if ( ! function_exists( 'storefront_credit' ) ) {
 function storefront_credit() {
  // contents for function here
 }
}

If you wanted to override that you would write another function with the same name (storefront_credit()) and hook it to the same hook as in the parent theme.

Unhooking a Function from the Parent Theme

If the function from the parent theme isn’t pluggable, you can still prevent it from running. Imagine your parent theme has a function called parent_function(), which is hooked to the init hook with a priority of 20. You want to prevent it from running so you can replace it with a function of your own.

Here’s what the parent theme function might look like:

function parent_function() {
 //contents of function here
}
add_action( ‘init’, ‘parent_function’, 20 );

To unhook it, you’d code this in your child theme:

function remove_parent_function() {
 remove_action( ‘init’, ‘parent_function’, 20 );
}
add_action( ‘wp_head’, ‘remove_parent_function’ );

Note that you hook your second function to the wp_head hook which is run at the top of each page, and that you have to include the same value for the priority parameter as in the original function. If the original add_action() function didn’t have a priority, you can omit that from your child theme’s remove_action() function.

Note: If the original function was hooked to a filter hook instead of an action hook, you would use remove_filter() in the same way.

Augmenting a Function With Another Function

Instead of overriding or removing a function, sometimes you might want to add to it instead. In this case, you’d write a new function with a different name, and attach it to the same hook.

Let’s imagine there is an action hook for the footer in your parent theme called parent_footer. Any function you attach to that hook will run in the place where the hook is situated.

In the parent theme, there’s already a function called parent_footer_content() that populates the footer. But what if you wanted to add some extra code to it?

Here’s what the parent_footer_content() function might look like in the parent theme:

function parent_footer_content() {
 // content of function here
}
add_action( ‘parent_footer’, ‘parent_footer_content’ );

Now if you wanted to add additional content after that, you would create a function in your child theme, hooked to the same action hook, with a priority that meant it run after the first function. As the priority isn’t set for the parent theme’s function, it defaults to 10. So you need to use a higher number so it fires after that.

function child_footer_extra_content() {
 // contents of function here
}
add_action( ‘parent_footer’, ‘child_footer_extra_content’, 20 );

This would add the code from your child theme’s function after the code from your parent theme’s function.

How to Troubleshoot Child and Parent Themes

So now you know how to create a child theme in WordPress and how to use it to override template files, to add extra styling, and to add functionality to your site.

But what if your child theme isn’t working as you expected? What if the content isn’t displayed the way you expected it to, or a function isn’t firing?

Use this checklist to troubleshoot your child theme:

1. Check that you have activated your child theme and that your parent theme isn’t still running. It’s surprisingly easy to forget this step!
2. Refresh your browser cache and the cache created by any plugins on your site.
3. Set wp-debug to true in your child theme’s wp-config.php file. If you’re looking at a white screen, there should be a message telling you what code has caused the problem and which file it’s in. This will help you to identify the bug and which file is being used.
4. Check the output code for your page, post or archive. Find the body element and see what classes it has. These will tell you what type of content you are looking at, which will help you identify which template file is being used. Sometimes it isn’t what you expect. For example, the main blog page never uses archive.php, even though it’s displaying an archive of your posts.
5. Check that you have named your files correctly. Refer to the template hierarchy to be sure that you’ve used the correct syntax.
6. If you duplicated a file from the parent theme and added it to your child theme, check that you’ve saved your changes.
7. If a function to override a pluggable function isn’t working, check that you’ve given it exactly the same name as the pluggable function and that the function in the parent theme is indeed pluggable.
8. If a function you removed is still firing, check that you added the correct priority and that your spelling is identical to the spelling of the function and the hook in the parent theme.
9. If you used priority to override or augment a function, try increasing the priority value, so you can be absolutely sure it fires last. Check there are no other functions attached to that hook which are interfering with your code.

Hopefully one or more of these steps will help you identify the problem and fix it in your child theme. Remember: do not edit the parent theme directly.

Useful Tips When Working with WordPress Child Themes

Phew! Child themes are quite a topic and an incredibly valuable feature of WordPress. I use them on every site I build.

To help you find the methods you need to use to make the most effective use of child themes, here are my tips to help you with them:

• If you need to edit a third party theme, always use a child theme instead. This way, your changes aren’t lost when you update the theme.
• Every child theme needs a stylesheet and a functions file.
• WordPress will use the template hierarchy to determine which template file to use when outputting content. If it finds two files with the same name, it will use the one from the child theme.
• You can override a pluggable function in your parent theme by writing a function with the same name in your child theme.
• You can unhook a function from the parent theme using a function with remove_action() or remove_filter() in your child theme and then writing a new function.
• You can augment a function in your parent theme by writing a function in your child theme and hooking it to the same action or filter hook.
• Don’t forget to activate your child theme after you upload it. And make sure no one deletes the parent theme from your WordPress installation: without it, the child theme won’t work.

Summary

Child themes are a useful feature of WordPress that let you customize a theme without directly editing its code. You can use one to add additional functionality to a theme, to customize the styling, or to create/edit template files.

If you follow the advice above, you’ll be able to create child themes in WordPress following best practices and take advantage of them for a variety of tasks. All without losing your changes and customizations when you’ll update the parent theme.