Understanding How WordPress Outputs Code From Child Themes
If you’ve ever needed to make tweaks to a third party theme, or you’re using a theme framework, you’ll be familiar with child themes.
They’re a powerful feature of WordPress, giving you the flexibility to make customizations to any parent theme without losing them when the theme is updated. I use them to make edits to third party themes, or with the framework theme I’ve developed myself.
However, it can sometimes be unclear whether WordPress will be using the code from your parent or your child theme. When it comes to template files, stylesheets and functions files, it can be tricky to work out what’s being used when.
In this post, I’ll demystify all this. I’ll look at each type of file and identify when WordPress will use the code from your parent theme and when it’ll use the code from your child theme.
Both your parent theme and your child theme will have a stylesheet, because no theme will function without a stylesheet.
In your child theme, your stylesheet will contain a line of code that tells WordPress that this is a child theme and which is the parent theme.
Here’s the theme I use for my website, which is a child theme. It opens with some commented out text that tells WordPress what’s going on with the theme:
Note the line that begins
template. This tells WordPress that this is a child theme and that the theme in the compassframework folder is the parent.
WordPress will use theme template files from both the child theme and the parent theme (more of which shortly). But if you want to pull in styling from your parent theme, you have to enqueue it in your child theme’s functions.php file.
Add the following to the functions.php file in your child theme. If your theme doesn’t have that file, create one, making sure you add an opening
<?php tag at the beginning of the file (you don’t need to add a closing tag at the end).
The code above assumes that the parent theme has only one stylesheet; if yours has multiple stylesheets, then you’ll need to enqueue each of them.
Once you’ve done that, the styles from your parent theme will be used on your site. If you’re also adding styles to your child theme, you’ll need to enqueue that stylesheet too. The code below ensures that if there’s duplication, the styles from the child theme will override those from the parent theme:
This enqueues the parent theme’s stylesheet first, followed by the child theme’s. Because the child theme’s styles are pulled in last, they will override those from the parent theme if you add styling for an element that already has styling in the parent theme. This also sets the parent theme’s stylesheet as a dependency for the child theme’s stylesheet, ensuring the child theme stylesheet can’t be loaded unless the one from the parent theme already has.
Note: you may have seen a line in the child theme’s stylesheet used for this in the past. This is no longer best practice because it slows down the loading of stylesheets – you should use the functions file instead.
Now let’s take a look at theme template files. Which WordPress uses to display a page on your site will depend on two things: the template hierarchy and the fact that you’re using a child theme.
So let’s say you’re viewing the ‘WordPress’ category archive page in your site. WordPress will use the template hierarchy to find the most relevant file:
- A category archive template file for that specific category, using the slug: category-wordpress.php
- A category archive template file for that specific category, using the ID: category-23.php
- A general category archive file: category.php
- A general archive file: archive.php
- The catch-all index.php
WordPress will look for these in both your parent and child theme. When it comes across the first file in the hierarchy it will use it, whether it’s in the parent theme or the child theme.
There’s one exception: when the most relevant template file has a version in both the parent and child themes, it will use the file from the child theme, and ignore the one from the parent theme. This is one of the most common uses for child themes.
Here are a few examples, using the category example above:
- If your child theme has archive.php and index.php and your parent theme has category.php and index.php, then WordPress will use category.php from the parent theme because it’s highest in the hierarchy.
- If your child theme has archive.php and index.php and your parent theme has archive.php and index.php, it will use the archive.php file from your child theme.
- If your child theme has category.php and index.php and your parent theme has archive.php and index.php, it will use the category.php file from the child theme, as this is highest in the hierarchy.
So if you want to override a template file in your parent theme, create a duplicate of that file in the child theme with the code you want.
The final kind of file affected by child and parent themes is the theme functions file. This also applies to functions you add to your themes via include files.
The functions from your child theme will load before those from your parent theme, assuming they’re attached to the same hook. This is the opposite from stylesheets and template files and means that if you’re not careful, the functions in your parent theme could override those in your child theme.
It’s important to note that writing a function in your child theme with the same name as one in your parent theme may cause an error. WordPress doesn’t like it when two functions have the same name. The exception to this is when you use a function in your child theme to override a pluggable function in your parent theme.
You can recognize a pluggable function because it will be wrapped in a conditional check for another function with the same name. In other words, the parent theme is checking whether a function with the same name has already been fired via the child theme. If so, it doesn’t run the function in the parent theme. So if your parent theme has pluggable functions, you can easily override these in your child theme.
Here’s an example of a pluggable function from my parent theme, compass framework:
In a child theme I can write another function with the same name which will override it:
This will be run instead of the function from the parent theme, because of that
if check. You don’t need to use
add_action() in your child theme to fire the function, as the
add_action() function in the parent theme will do that for the one from your child theme instead. This is because it’s outside that conditional check.
Using Priority to Run Parent Theme Functions First
When I say that the functions from your child theme will run before those from your parent theme (when attached to the same hook), I’m assuming that they don’t have priority assigned to them.
Priority is the third parameter of the
add_filter() functions. The higher the number you use for this, the later the function will fire. So if a hook has four functions attached to it, with priority
30, then they will fire in ascending numerical order. It doesn’t matter what numbers you use; I tend to use round numbers so there’s a gap in case I need to insert another function at a later date.
If you don’t apply priority to a function, WordPress gives it the default priority of
10. So if there’s a function in your parent theme with no priority attached, and you want to run another function on the same hook from your child theme, and have it fire after the one from the parent theme, just give it a priority higher than
Let’s take the pluggable function I used before, which has no priority parameter for the
add_action() function. If you want to run some other code immediately after it from your child theme, use priority, like this:
This will add another section with the name of the post author and a link to their archive page, after the date.
If a function in your parent theme isn’t pluggable, but you want to write a function in your child theme to override it, you can still do so. You’ll need to unhook the function from the parent theme from the hook used to fire it, which means it then won’t fire. You then write a function with a different name in your child theme to override it, and hook that to the same hook.
Let’s imagine my pluggable
compass_posted_on() function in the example above isn’t pluggable. In the parent theme, it looks like this:
To override it, first you unhook it using the
remove_action() function, which you hook to the
You then code a new function into your child theme with a different name, and hook it to the same hook:
Understanding Parent and Child Themes Will Help You Make Better Use of Them
The guide above will help you to better understand what WordPress will do with the code from both your parent and child theme when you’re using child themes. It will help you to troubleshoot situations when the code you’re expecting isn’t being used. It will also help you to write better and more efficient code in your child themes.