How to Create a WordPress Child Theme

WordPress themes can be amazing but there are so many examples of little things we all want to change. A color here, a font size there, perhaps use a different call to action on the buttons?

The problem is that modifying a theme even slightly prevents you from updating it to a newer version in the future, because if you do try to update, you lose all your changes.

Child themes solve this by allowing you to use all of the functionality of your chosen theme while allowing you to update it without the fear of losing your modifications.

In today’s Weekend WordPress Project, I’ll explain why you should be using a child theme and how you can get the job done.

How Child Themes Work And Why Use Them

Child themes are separate themes that rely on a parent theme for most of their functionality. If you are using a child theme, WordPress will check your child theme first to see if a specific functionality exists. If it doesn’t, it will use the parent theme. This is great because it allows you to modify only what you need.

Child themes should always be used if you plan on modifying even a single character in your theme. There are two very good reasons: updates and organization.

Updates

If you modify a theme without using a child theme you have two choices: You can opt to not update your theme in future, or you can update and lose any changes you’ve made to your theme.

The later option would technically work, but it is not recommended. Even if your changes are easy to copy and paste, why spend two minutes on an error-prone task on each update?

Not updating your theme should be out of the question. Almost all “why your website was hacked” lists contain outdated software as a top cause for security issues. You should always keep WordPress, your themes and plugins up to date, no exceptions.

Organization

When you add code to an existing theme you are adding to a codebase, which may be thousands and thousands of lines. Developers working on your site (and, indeed, you yourself) will have a hard time tracking down your changes. At least one direct result of this will be an increased development bill.

Since child themes fall back on parent themes unless otherwise specified, your child theme is essentially a changeset to an existing theme. This can result in extensive changes even though the child theme only has a couple of files and maybe 100 lines of code.

Creating A Child Theme

Creating a child theme is extremely simple, so much so you can copy and paste my example below.

To create a child theme for your theme, you will need to do the following steps:

  1. Create a theme directory in your WordPress install
  2. Create a stylesheet with information about your child theme
  3. Pull in the styles of your parent theme

Once these steps are completed you can activate your child theme and your website will look exactly the same as before, but it will be using your child theme.

So let’s go through the above steps in detail. For this example, I will be creating a child theme for the Twenty Fourteen default theme.

1. First, go to your theme directory and create a folder for your new theme. You may name it anything you’d like. For clarity’s sake, I will name my theme twentyfourteen-child.

2. The next step is to create a stylesheet file. This must be named style.css. Copy and paste the following code into the file you’ve just created:

The two necessary items in the code above are the lines starting with “Theme Name" and “Template.” The theme name tells WordPress what the name of your theme is, and this is displayed in the theme selector. The template tells WordPress which theme it should consider as the parent theme. Most of the others are self-explanatory, with the exception of the text domain and the tags. The text domain is used for translating strings. The text domain should be unique for your theme and should be used whenever you use translation functions. See I18n for WordPress Developers for more information. The tags section is a list of tags that are used by the WordPress Theme Repository. For this example I looked at the style.css file of the parent theme and simply copy-pasted the tags from there.

3. At this point your child theme works just fine. If you activate it and reload the page all your content will be there but, it will have no styling information. I mentioned before that WordPress first looks for functionality in the child theme and if it isn’t present it falls back on the parent theme.

In our case we do have a stylesheet, so WordPress figures it shouldn’t load the parent file’s. To make sure we load the parent file’s stylesheet we will need to enqueue it. This can be done in the theme’s functions.php file, so go ahead and create that file now. In this file, copy-paste the following code:

If you have no idea about PHP and you just want to change some styles, don’t worry about why this works. Feel free to go into your stylesheet file now and start making your changes. If you would like to learn more about enqueueing we have you covered right here on WPMU DEV with Adding Scripts and Styles to WordPress the Right Way With Enqueueing.

Child Theme Mechanics

So how does a child theme actually work? Child themes work on a file-level. When a file is used during the process of loading a theme it checks if it is present in the child theme. If it is, the content of that file is used. If it isn’t, the same file in the parent theme is used.

There is one exception to this rule, the theme’s functions file. The functions.php file in both the parent and the child theme is loaded. If the child theme’s functions replaced the parents you would either have a malfunctioning site, or you would need to copy-paste the entire contents of the parent theme’s function file into the child theme’s which would sort of defeat the purpose of extending a theme.

The workflow when modifying functionality is the following. If you want to make changes to the header, copy-paste the parent theme’s header.php file into your child theme. Edit the file to your heart’s content, save it and enjoy the fruits of your labour.

Some Notes For Theme Makers

If you make your own themes there are a couple of guidelines you may want to follow to make child theme creation easier. The two most important ones are learning the difference between get_stylehseet_directory() and get_template_directory() and creating pluggable functions.

The Right Directory

When linking to assets using the mentioned functions you should always be aware that the get_template_ family of functions will always point to the directory of the parent theme while the get_stylesheet_ family of functions will always point to the child theme’s directory.

In the example above the first link takes its image from the parent theme, the second takes it from the child theme. There’s no good answer to which one you should use, it’s up to you.

The upside to using get_stylesheet_directory_uri() is that child theme developers can use their own image by simply creating it in the proper location. On the other hand, if the image doesn’t exist in the child theme it won’t be shown at all.

The reason for this is that if a child theme is active the get_stylesheet_directory_uri() function doesn’t check (and doesn’t know) which file you are loading so it won’t check for its existence, it will always spit back the URI for the child theme.

Modifiable Functions

The other method you should use is what WordPress calls pluggable functions. This makes it possible for child theme authors to overwrite the functions you define in the parent theme. This involves wrapping your functions in function_exists() checks.

Let’s presume you create a function for a customized post meta display named my_meta(). There is no way a child theme can modify this function because it can not be defined twice. The solution is to only create this function if it hasn’t been defined (remember, the child theme’s function file is loaded first).

Conclusion

Using a few very simple copy-pastable steps you can create a future-proofed environment for your theme, which will save you a lot of headaches. While it may be tempting to use the built-in theme editor in WordPress, it almost always causes more issues than it solves if you’re not using a child theme.

Take a few minutes to follow along the tutorial here and your website and your developer will thank you for it. Finally, If you have any great tips about child themes, do let us know.

41 Responses

    Lazlototh

    As a new user to user to WordPress (and web development) I did not discover the power of child themes until a few of months ago.

    As a newbie one thing that I really struggled with when I first started to experiment with child themes was how to create the correct file/folder structure as I attempted to make modifications beyond the themes functions.php and style.css files.

    Two plugins that have helped me immensely are:
    https://wordpress.org/plugins/orbisius-child-theme-creator/
    https://wordpress.org/plugins/child-theme-configurator/

    Orbisius Child Theme Creator is great for both creating and editing a child theme but I really like using both plugins together.

    What I really like about Child Theme Configurator is that it does all the tedious work for you. It not only creates your desired child theme document but it also automatically replicates all of the folders and sub-folders that are required to make it accessible to your parent theme.

    ExtremRaym

    Thanks fo rhtis article !
    What is the best way to rewrite the CSS responsive rules (aka. media-queries width) in the child theme ?

    Copy paste the whole parent CSS in child ?
    Use some !important;
    other ?

    Daniel Pataki

    Hi ExtremRaym,

    Thank you :) I definitely don’t recommend copy-pasting the parent stylesheet, make sure to enqueue it like in the article.

    After that you’ll need to overwrite it with at least the same specificity. I usually use developer tools to take a look at the exact styles being used. For example: if the theme author specified form#commentform you won’t be able to overwrite that with #commentform in the stylesheet, you’ll need to use at least form#commentform as well.

    While important rules should also work, I would recommend trying to find the specificity used and replicating it, keeping track of important rules is very difficult :)

    ExtremRaym

    Thanks daniel :)
    Replacing some CSS using priorities is fine.
    The fact is that some theme developers but a LOT of things in a single media query. I mean it, a lot. And if we want to change the width of this responsive behavior (for exemple, all the width at which the sidebar collapse etc…) we have to rewrite a lot of rules… and try to avoid media queries width conflict.

    So what is the best way for that kind of scenario ? :)

    And for theme developper, what is the best way to make a customizable responsive behavior ? Having an responsive.css stylesheet ? have some theme options for this ? :)

    Daniel Pataki

    You can rewrite individual rules within a media query, even if there are multiple selectors in there, like this:

    In parent theme:

    @media_query_1 {
    #comment_form {
    width: 400px;
    }
    #response {
    width: 300px;
    }
    }

    In the child theme:

    @media_query_1 {
    #comment_form {
    width: 200px;
    }
    }

    You don’t need to copy-paste the whole thing, just whatever you need. There’s no really good way to prevent you from doing a lot of work if you want to change many things I think.

    Having theme options is probably not the best idea since it would be difficult to add all of them and would only be useful for developers.

    I would definitely use a responsive stylesheet. Or I would use a responsive sass file which is compiled into style.css. If you supply all your sass files developers creating child themes can just use those files to compile their own css file, changing the responsiveness as needed.

    ExtremRaym

    I was thinking of a example more like this :

    @media (min-width: 200px) {
    .element {
    property: value;
    }
    }

    which became

    @media (min-width: 300px) {
    .element {
    property: value;
    }
    }

    (is is the query value that change, not the values).

    Ok for the theme options,
    and indeed, sass seems a good idea !

    Daniel Pataki

    Ah, I see what you mean now! I think even in that case it should be enough to change just the values you need. Of course if you want to change all of them then yes, you’ll probably need to copy-paste all the rules :(

    SASS gets around this but not many themes offer it at the moment :)

    Daniel

    Dan

    Nice walkthrough for some of the main points in the Codex on child themes. Overriding functions in the parent theme is probably the most challenging part, so I’d add a couple of pointers on the main sticking points to explain what is actually going on when you want to override or remove parent theme functions.

    If the parent theme functions are not “pluggable,” then they will execute after the child theme without regard to anything it does. Typically this means the parent functions.php will add a filter that you can’t override in the child theme just by pre-emptively defining it there.

    If the parent theme functions *are* “pluggable,” then they won’t be defined by the parent if the child has already defined them, but defining them differently in the child theme is not the same as “unplugging”/removing them.

    If you want to truly “unplug”/remove a parent theme function whether it is pluggable or not, you need to have the child theme unhook the parent theme function after the parent theme function is executed. Even though the parent executes after the child, you can have a child function that unhooks a parent function after the parent executes.

    A good old resource on this:
    http://ottopress.com/2010/wordpress-protip-child-themes/

    From a performance standpoint, I’ve wondered if it is better to negate pluggable parent functions by defining them as do nothings in the child or to do it the old way: have the child unhook parent functions after the parent adds them. The latter method is more confusing and inelegant/convoluted, but it is less efficient? Might it be preferable in some cases?

      Daniel Pataki

      Hi There!

      I think reading the article will get you there :) Creating a child theme is the same process for everyone!

      The only thing you need to be aware of is that some themes which are badly coded may not support child themes properly. If you are a beginner I recommend creating a child theme for a default WordPress theme like Twenty Fourteen first.

      Daniel

      Daniel Pataki

      Hi Tung,

      Importing the stylesheet isn’t necessary, but you will need to write all the styles yourself which could be a LOT of work.

      Also, importing it is not the recommended way, you should enqueue it like I show in the article. There is no immediate difference in functionality between the two methods but enqueueing is much more modular :)

      Daniel

        Tung

        Also about the functions.php in the child theme’s folder, do we need to copy the content of its parent theme functions.php before inputing the enqueue?
        Thank Daniel

          Daniel Pataki

          Hi Tung,

          That’s a great question. No, you do NOT need to copy the content of the functions file. The functions file is a special case. The parent theme’s function file is ALWAYS loaded in addition to the child theme’s function file.

          Hope this helps,

          Daniel

    Leroy

    Daniel,

    I may have missed it or misread it, but when you enqueue for a child theme do you add the line of php code to the child theme’s function.php or the parent?

    Thanks,
    Roy

    Geoff

    Hi Daniel,

    Something to note that got me into trouble. The raw code does not include “<?php" which must be included on the first line without white spaces or you will get error messages like "Warning: Cannot modify header information – headers already sent…"

    Thanks,
    Geoff

      Daniel Pataki

      Hi Geoff,

      Sorry about that, I was a bit torn on wether or not too add that. The problem is that you only need the PHP start tag at the top of the file. If I add it to a snippet I was afraid that someone would think that it is standard to add it to all snippets.

      I realize now that I should have pointed out that you need to start the file with the start tag, but I’m glad you found your way :)

      Daniel

    Daniel Pataki

    Hi Ilinet,

    It is not impossible, but it would take a lot of time, effort, and it would only work if you documented your code modifications heavily. I would not recommend doing it at this point unless you really-really know what you are doing :)

    Making a child theme should be the very first thing you do. I realize this is water under the bridge now, but for upcoming projects it may be helpful :)

    Daniel

    Seth

    I’ve followed these instructions exactly but when i go back in to my site admin page and try to activate my twentyfifteen-child theme it’s not showing up. any ideas?

      Daniel Pataki

      Hi Seth,

      There could be quite a few reasons. You need to makes sure you’ve created the folder within the wp-content/themes directory and that it contains style.css. The file needs to be named that exactly, make sure you haven’t added a space before or after the filename.

      It’s also possible that you’re working on a multisite installation and you need to activate the theme from the main network dashboard.

      Daniel

    Mary

    WordPress would cut down on a TREMENDOUS number of Support tickets if they just
    1. added a child theme file called ‘child-theme’ to the basic WP package.
    2. Wrote MUCH better documentation!! This tutorial is a perfect example of WHY they need better documentation. The tutorial and ALL the documentation ASSUMES that the WP user already knows HTML, CSS, and understands PHP. This is certainly NOT explained when you first subscribe. The subscription isn’t cheap, and for the price you’d think you could get better documentation. EXPLAINING how to do things for a non-internet development user (a LARGE PERCENTAGE of those buying their product) would save all those Support tickets and save their users TONS of time.

    The first paragraph above says the following: “Creating a child theme is extremely simple, so much so you can copy and paste my example below.”

    NO, it’s NOT extremely simple if you don’t know how to do the next three steps: “To create a child theme for your theme, you will need to do the following steps:
    Create a theme directory in your WordPress install
    Create a stylesheet with information about your child theme
    Pull in the styles of your parent theme”

    And WHERE is the documentation or examples of how to do those three steps?

    Likely no one that works at WP will ever reply to this comment, but it really burns me up that they aren’t more proactive about making their product usable for MORE users. It’s only more $$ for them if they did.

      Raelene Wilson

      Hi Mary,

      I’m a bit confused about your post. By WordPress are you referring to WordPress.org? If so, the WordPress software is free and the support forums are moderated by volunteers, so it can take a while for new tickets to be addressed.

      If you’re referring to WPMU DEV, I can get one of our support staff members to contact you if you need help with using child themes, though this post offers a comprehensive rundown of how to do it.

      Hope that helps!

      Cheers,
      Rae

        Jdirks

        Maybe I can shed some light.

        There have been a couple comments like this now that refer to step 1. I’m a beginner and it took me a little bit to figure out that “Create a theme directory in your WordPress install” meant I had to either 1. Figure out FTP software to manage files or 2. go into my host cPanel to manage files.

        Most folks (like myself) don’t know even the little things that you might consider a ‘given’. Hope that helps!

          Daniel Pataki

          Hi Jdirks,

          I completely understand your issue, however, this is not something we can solve in an article like this. Since the article is about child themes, devoting 2,000 words to pre-requisite knowledge.

          Just like a recipe won’t contain information about how to use the oven, it will just say “bake for 40 minutes at 200C”.

          That being said, I think we all recognise that some people don’t know the fundamentals, after all, we were all there at some point! I’ll look into writing an article for you guys where I cover most of the bases like creating folders in the theme folder, FTP and so on.

          Daniel

    Jason

    I’ve noticed that everything seems to be case sensitive. This could be a huge hangup to doing this correctly. I’ve done alot of child themes with the old method and this one was driving me nuts. make sure your Theme: designation in your child css file is case sensitive to the main theme file name. I know, seems simple, but it will save you time knowing this.

    Paul

    Wondering if someone could help..

    So I followed this instruction as best as I could, and I managed to get a child themed website up and running, the only issue was that it said the menu was missing. Styles and everything else was correct, just no menu. Any ideas?

    Amy

    I followed these instructions to the letter, and my child-theme-based site looks VASTLY different from the parent theme. In the WordPress Codex it says this: The following example function will only work if your Parent Theme uses only one main style.css to hold all of the css. If your theme has more than one .css file (eg. ie.css, style.css, main.css) then you will have to make sure to maintain all of the Parent Theme dependencies.

    There are presumably a gazillion .css files within the whole parent theme, I’ve already found just two inside a font-awesome folder and that’s the first thing I looked at.

    So…how do I “make sure to maintain all of the Parent Theme dependencies”? Do I have to repeat that whole add_action code snippet for each and every .css file?

      Daniel Pataki

      Sloppy code in parent themes is sadly a problem, it’s really the parent themes responsibility to take care of things like this. The parent should either concatenate everything into style.css or enqueue properly.

      Also, be aware that not every stylesheet is used just because it is inside the theme folder. Many themes concatenate their CSS AND leave all the source files in there.

      That being said, if you need the extra CSS files, perhaps the best method is to copy them over and enqueue them.

      Daniel

        Amy

        Ok thanks. When you say “copy them over and enqueue them” that means I create a matching .css file in my child theme and add that enqueue statement above to my functions.php file, just replacing the name of the .css file, right?

          Daniel Pataki

          Yep, but you don’t need to rename it, the issue is that they don’t seem to be enqueued at all. Perhaps you can go into the parent theme’s CSS file and just copy and reuse all the enqueueing code, except for the line that enqueues the main stylesheet.

          Daniel

    Julius

    Is it me or am I missing something? In the tutorial it says “2. The next step is to create a stylesheet file. This must be named style.css. Copy and paste the following code into the file you’ve just created:” but I don’t see any code. Am I missing something?

    Julius

    Disregard obviously my internet was having loading issues.

    However, I have everything up and running but I am receiving the following error message on the website when activating the child theme, “add_action( ‘wp_enqueue_scripts’, ‘enqueue_parent_styles’ ); function enqueue_parent_styles() { wp_enqueue_style( ‘parent-style’, get_template_directory_uri().’/style.css’ ); }
    Image placeholder
    Text element with no background color applied
    Text element with background color applied gets additional padding to prevent text running into sides”

    I followed the instructions as given. Does anyone have any idea the problem here?

    Roy

    I had this problem but spotted the solution in the comments above.

    Something to note that got me into trouble. The raw code does not include “<?php" which must be included on the first line without white spaces or you will get error messages like "Warning: Cannot modify header information – headers already sent…"

    Put this as the first line in your functions.php file that you created in the child theme folder.

    Sotexis

    Maybe I overlooked something in the functions.php of the child theme:

    Q1: Must I put <?php before each code snippet?
    Q2.1: Can I add endlessly modification snippets to the child theme functions file?
    Q2.2: How does the parent know where to add or use the snippet in the parent function theme?
    Q3.1: The parent theme have a maps and files structure, if I modify in my child theme vatious files in various maps, must I than follow the same maps and files structure of the parent or can I list all the modified files in one row?
    Q3.2: If I can list all the modified files in one row, what to do with the different modified image files of the parent theme?

    Hope to hear more from you,

    Sotexis

    Sotexis

    Sorry, I forgot one question:
    Q4: Can I have more than one child themes in one installation, like one as main child theme and more than one grandchildren themes?