Imagine this scenario: There’s a WordPress theme that you really like and it’s nearly perfect, but there are a few things you want to change. Unfortunately, the theme’s built-in options won’t let you make the adjustments you want. You could modify the theme’s code directly but could cause an issue because if you update the theme to a newer version, all your changes will be lost. You could use a custom CSS plugin, but that won’t let you make changes to other code, like the theme’s templates or JavaScript.
So what do you do? How do you make customizations that theme options and a custom CSS plugin can’t handle? The simple answer is you create a WordPress child theme.
What’s a WordPress child theme?
The WordPress codex provides the following description for a child theme:
“A WordPress child theme is a theme that inherits the functionality of another theme, called the parent theme. Child themes allow you to modify, or add to the functionality of that parent theme. A child theme is the safest and easiest way to modify an existing theme, whether you want to make a few tiny changes or extensive changes. Instead of modifying the theme files directly, you can create a child theme and override within.”
In other words, a WordPress child theme inherits everything from the “parent theme” — another theme that is installed (but not activated) on your website or blog. Modifications from the child theme are applied on top of the parent theme. When the parent theme gets updated, the child theme inherits those changes, but the child theme’s modifications aren’t lost.
How to create a WordPress child theme
In this article, we’re going to cover the key components of what makes a good WordPress child theme. We’ll also point you in the right direction for further in-depth reading.
- Know when to use a child theme
- Choose a good parent theme
- Set up your development environment
- Create your new theme folder
- Create the style.css
- Create the functions.php
- Add custom CSS
- Use hooks and filters
- Override templates
- Test your changes
- Package your theme
There’s a lot to go over. Let’s get to it!
1. Know when you should use a child theme
Child themes are fantastically convenient, but they’re not the right solution every time. If you’re just looking to make some simple visual tweaks to a theme, applying some custom CSS or using a page builder plugin might be a better option.
That said, there are a few common scenarios where child themes come in handy:
Custom websites for clients
When you’re building a website for a client, chances are they’ll want some level of customization above and beyond what you can do through theme options and plugins alone. Try using a standard parent theme for all of your sites, then creating a child theme for each client. This way, you can let the parent theme do the heavy lifting and focus your time and resources on customizing the child theme to suit your client’s requirements.
Adding custom PHP or JavaScript
If you’re writing PHP or JavaScript that’s dependent on the theme (e.g., changing the theme would make the code irrelevant/useless), then that code should live within the child theme.
Releasing variations of an existing theme
This is similar to the first scenario, except instead of creating custom child themes for clients, you’re creating child themes as standalone products. StudioPress themes are a great example of this approach. Their entire theme library is made up of child themes built on top of the Genesis parent theme.
So what goes into choosing a good parent theme? Great question!
2. Choose a good parent theme
When you know you want to create a child theme, the next step is to choose a good parent theme to build on top of. Generally speaking, you should look for the following:
Neutral design
A good parent theme is like a blank canvas. It’s unopinionated, with a clean and minimalist aesthetic that you can build on top of. There are exceptions to this, of course. Working with a client and have an existing theme in mind with the perfect style? Run with it. The purpose of the neutral design is to minimize the amount of un-designing you need to do.
Clean HTML
Open the page source and look at the HTML. Are element IDs and classes clearly named? Does the page structure make sense, or is it a muddled mess of div soup? These might seem like minor details, but it’s a lot easier to deal with a parent theme that uses clean HTML.
Documentation and support
Is the theme well-documented for both users and developers? On the user side, look for documentation around theme options and plugin compatibility. On the developer side, look for documentation around hooks and filters (we’ll come back to that later).
What about support? Is there a dedicated support channel, like email or a ticketing system? What are people saying about the level of support? This is particularly important if you plan to use the parent theme a lot.
There are purpose-built themes out there known as WordPress theme frameworks. These themes have been designed specifically for use as parent themes. A few examples of popular theme frameworks include Genesis, Hybrid Core and GeneratePress (my personal favorite).
It’s worth noting that these theme frameworks work just fine as standalone themes, by the way.
3. Set up your development environment
At this point, you should have a parent theme chosen and be ready to start working on the child theme. But before we jump into it, you need to set up a development environment — in other words, the WordPress site where you’ll test and tweak your child theme.
If you plan on applying the child theme to an existing website, you should do your development on a copy of the site. That way, you’ll see exactly how everything will look once you push the changes live on the site.
If you’re using a managed WordPress hosting provider like GoDaddy’s WordPress Hosting, you can use your one-click staging site as a development environment. If you’re using something like cPanel or VPS for hosting, you can set up a separate WordPress installation and use GoDaddy Pro Sites to clone (copy) your existing site over to the new installation.
If you’re not applying the child theme to an existing site, or if you’d rather build from scratch, you can create a local WordPress development environment on your computer using a tool like MAMP or DesktopServer from ServerPress.
When your development environment is ready to go, it’s time to create the theme.
4. Create your new theme folder
First things first: Install the parent theme you want to build on top of. Then, using an FTP client, connect to your development environment and navigate to where your WordPress files are located.
You’re looking for the following folder:
/wp-content/themes/
That’s where you can find all of your installed WordPress themes. Each theme has its own folder (directory) that contains all of the theme’s files. You’re going to add a new directory to the list, which will hold your child theme. So you’ll end up with something like:
/wp-content/themes/your-child-theme-name/
Within that folder, you’re going to create two new files:
style.css
functions.php
Both of these files serve a specific purpose. The style.css file is used to provide WordPress with information about the theme, like the name, author, tags and parent theme ID. The functions.php file is used to pull in files from the parent theme, plus we can use it to apply new code to hooks and filters within the parent theme (more on that in a moment).
5. Create the style.css
The first step is to add the theme header to your stylesheet. Here’s the example header provided in the WordPress codex:
/*
Theme Name: Twenty Fifteen Child
Theme URI: http://example.com/twenty-fifteen-child/
Description: Twenty Fifteen Child Theme
Author: John Doe
Author URI: http://example.com
Template: twentyfifteen
Version: 1.0.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Tags: light, dark, two-columns, right-sidebar, responsive-layout, accessibility-ready
Text Domain: twenty-fifteen-child
*/
The Template Name: corresponds to the folder (directory) name of the parent theme you’re building on top of. The Text Domain: name is unique to your WordPress child theme.
6. Create the functions.php
After your style.css file is set and saved, you need to enqueue both the parent theme style.css and the child theme style.css in your child theme. Open up your functions.php file and create a new function to enqueue the stylesheets.
Again, taking from the Codex example:
function my_theme_enqueue_styles() {
$parent_style = 'parent-style'; // This is 'twentyfifteen-style' for the Twenty Fifteen theme.
wp_enqueue_style( $parent_style, get_template_directory_uri() . '/style.css' );
wp_enqueue_style( 'child-style', get_stylesheet_directory_uri() . '/style.css', array( $parent_style ), wp_get_theme()->get('Version') );
}
add_action( 'wp_enqueue_scripts', 'my_theme_enqueue_styles' );
A few things are happening here:
- You’re setting the name of the parent theme’s style.css
- You’re enqueuing the parent theme’s style.css
- You’re enqueuing the child theme’s style.css
Save your functions.php, then head over to Appearance > Themes in your WordPress admin area. You should now be able to activate your new child theme. If everything’s working as intended, congrats! You now have a functioning WordPress child theme.
The next step is to start applying your customizations.
7. Add custom CSS
You can start applying new CSS rules in your child theme’s style.css file. Check your parent theme’s source code to determine what IDs and classes you need to target.
Need help with CSS? Check these resources:
- Introduction to CSS from the Mozilla Developer Network
- CSS reference from Codrops
- CSS-Tricks guide to HTML & CSS
Once you get a good grip on that, it’s time to look at hooks and filters.
8. Use hooks and filters
You can start adding custom functions to functions.php to drop custom blocks of code into specific areas of your parent theme. These “specific areas” are called hooks, and the available hooks will depend on the theme that you’re using. GeneratePress, for example, has well-documented hooks available throughout the theme.
Unlike hooks, filters work by processing and modifying data loaded by WordPress. Again, the available filters will depend on the theme that you’re using. And again, GeneratePress is a good example of well-documented filters.
Want to learn more about WordPress hooks and filters?
- Beginner’s guide to Actions and Filters (Tuts+)
- WordPress Hooks: Actions, Filters, and Examples (Treehouse)
- Plugin API filter reference and action reference (Codex)
Now, let’s look at overriding templates for your WordPress child theme.
9. Override templates
What if you want to do more than what hooks and filters allow? What if you want to make dramatic changes to individual template files? That’s where template overrides come into play. Within your WordPress child theme folder, you can override any template files by using the same name as those found in the parent theme folder.
So let’s take a parent theme’s single.php, for example:
/wp-content/themes/parent-theme/single.php
If you want to override that template file, your child theme should contain a single.php as well:
/wp-content/themes/child-theme/single.php
Understanding the WordPress template hierarchy comes in handy here. In some cases, you might not even need to override the parent theme template. Instead, supplementing the existing templates with new ones may get the job done. If you want a deeper dive, refer to the WordPress Codex for further reading on working with template files in a child theme.
10. Test your changes
Even though you’re customizing an existing theme, you should still follow due diligence and perform some basic QA on your work.
If you’re developing your child theme on a fresh WordPress installation, either the official Theme Unit Test or the unofficial WP Test will come in handy. Importing these tests using the WordPress Importer will load their test content into your site as posts, pages, categories and tags.
The Developer plugin will also come in handy on your development environment. After activating the plugin, you can choose the type of development you’re doing. Select “theme development,” and the plugin will recommend additional plugins to use.
And, of course, you should be testing your work across multiple devices.
If you don’t have access to a bunch of devices, a service like BrowserStack or Browser Sandbox (Windows only) will emulate other devices within your browser. The developer tools within your browser (Chrome/Edge/Firefox/Safari) also offer a limited scope of device emulation, mostly for testing responsiveness.
Further reading on theme testing and QA, check out these resources:
- Tips and tricks for testing WordPress themes (Smashing Magazine)
- How to QA WordPress websites like a pro (WebDevStudios)
You’re just about finished with your WordPress child theme. Now, it’s time to package it.
11. Package your theme
So you’ve created your child theme and ran it through a bunch of tests. Congratulations! If you’re working on this theme for a client — i.e., the theme won’t be released for public consumption — you could just stop here and move on to other tasks.
But maybe you want to release it publicly, as a theme that other people can download and use. In that case, you have a few more to-do items to tackle.
Ensure your theme meets repository requirements
Even if you’re not planning to submit your theme to the official WordPress.org theme repository, you should still review the submission requirements. It’s a thorough checklist that will prepare your theme for use by others. For example, it outlines requirements for documentation, language and translation support, code formatting, licensing and much more.
Review the “Designing themes for public consumption” Codex article
Above and beyond technical best practices, this guide in the Codex provides a bunch of recommendations to set you up for success. It walks you through the entire process, from initial planning to theme promotion.
Put your code online for peer review
The developer community that’s built up around WordPress is wonderfully supportive, so once you’ve covered the above, get your theme up on a public repo (e.g., GitHub or BitBucket) so others can review, comment, and (in an ideal world) make further improvements to the code.
Final recap your child theme create steps
We’ve covered a lot in this post, and now hopefully you’ve got a good grip on how to create a WordPress child theme. Let’s do a quick recap.
- Know when to use a child theme - Sometimes, the tweaks you want can be covered through simple custom CSS or the use of a page builder plugin. That said, child themes are great if you’re a developer building custom themes for clients. You can use one theme as a “base” and make adjustments via the child theme.
- Choose a good parent theme - A good parent theme is a blank slate for you to add customizations on top. It should be well-coded, well-documented and well-supported. Theme frameworks are special WordPress themes built specifically for child themes.
- Set up your development environment - Applying a child theme to an existing site? Use a staging environment to see how the child theme affects existing content. Otherwise, set up a development environment to work with.
- Create your new theme folder - Your child theme lives in the same /wp-content/themes/ folder as the parent theme you’re customizing.
- Create the style.css - The style.css file includes details about your theme and any custom CSS you’re writing.
- Create the functions.php - The functions.php file enqueues the style.css from your parent theme and child theme. It’s also where you’ll drop in any functions that you want to apply to WordPress hooks and filters.
- Add custom CSS - Add your custom CSS to the style.css file you created.
- Use hooks and filters - Beyond the core WordPress hooks and filters, your parent theme should have additional hooks and filters available for you to work with. Look for documentation from the parent theme’s developer.
- Override templates - If you want to make more drastic changes than what hooks and filters allow, you can override templates in the parent theme by creating template files with the same name in your child theme.
- Test your changes - After you’ve finished developing your child theme, perform some basic QA tests. See how the theme affects content and how it performs across different devices. The Developer plugin can come in handy here.
Bonus content: Packaging your theme for public usage
If you want to release your theme for public consumption, refer to guidelines from the WordPress Developers Handbook and WordPress Codex. Put your theme out on a public repo for other developers to review, comment and contribute to your code.
That’s everything! I hope this post helped you figure out how to create a WordPress child theme.
