WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Child Themes

A child theme is a theme that inherits the functionality and styling of another theme, called the parent theme. Child themes are the recommended way of modifying an existing theme.

Why use a Child Theme?

There are a few reasons why you would want to use a child theme:

  • If you modify a theme directly and it is updated, then your modifications may be lost. By using a child theme you will ensure that your modifications are preserved.
  • Using a child theme can speed up development time.
  • Using a child theme is a great way to to learn about WordPress theme development.

How to Create a Child Theme

Child Theme directory structure

A child theme consists of at least one directory (the child theme directory) and two files (style.css and functions.php), which you will need to create:

  • The child theme directory
  • style.css
  • functions.php

The first step in creating a child theme is to create the child theme directory, which will be placed in wp-content/themes. It is recommended (though not required, especially if you're creating a theme for public use) that the name of your child theme directory is appended with '-child'. You will also want to make sure that there are no spaces in your child theme directory name, which may result in errors. In the screenshot above we have called our child theme 'twentyfifteen-child', indicating that the parent theme is the Twenty Fifteen theme.

The next step is to create your child theme's stylesheet (style.css). The stylesheet must begin with the following (the stylesheet header):

/*
 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
*/

A couple things to note:

  • You will need to replace the example text with the details relevant to your theme.
  • The Template line corresponds to the directory name of the parent theme. The parent theme in our example is the Twenty Fifteen theme, so the Template will be twentyfifteen. You may be working with a different theme, so adjust accordingly.
  • The only required child theme file is style.css, but functions.php is necessary to enqueue styles correctly (below).

The final step is to enqueue the parent and child theme stylesheets. Note that the previous method was to import the parent theme stylesheet using @import: this is no longer best practice. The correct method of enqueuing the parent theme stylesheet is to use wp_enqueue_script() in your child theme's functions.php. You will therefore need to create a functions.php in your child theme directory. The first line of your child theme's functions.php will be an opening PHP tag (<?php), after which you can enqueue your parent and child theme stylesheets with the following function (setting 'parent-style' as a dependency will ensure that the child theme stylesheet loads after it):

add_action( 'wp_enqueue_scripts', 'theme_enqueue_styles' );
function theme_enqueue_styles() {
    wp_enqueue_style( 'parent-style', get_template_directory_uri() . '/style.css' );
    wp_enqueue_style( 'child-style', get_stylesheet_uri(), array( 'parent-style' ) );
}

Your child theme is now ready for activation. Log in to your site's administration panel, and go to Administration Panels > Appearance > Themes. You should see your child theme listed and ready for activation. (If your WordPress installation is multi-site enabled, then you may need to switch to your network administration panel to enable the theme (within the Network Admin Themes Screen tab). You can then switch back to your site-specific WordPress administration panel to activate your child theme.)

Note: You may need to re-save your menu (Appearance > Menus, or Appearance > Customize > Menus) and theme options (including background and header images) after activating the child theme.

Template Files

If you want to change more than just the stylesheet, your child theme can override any file in the parent theme: simply include a file of the same name in the child theme directory, and it will override the equivalent file in the parent theme directory when your site loads. For instance, if you want to change the PHP code for the site header, you can include a header.php in your child theme's directory, and that file will be used instead of the parent theme's header.php.

You can also include files in the child theme that are not included in the parent theme. For instance, you might want to create a more specific template than is found in your parent theme, such as a template for a specific page or category archive. See the Template Hierarchy for more information about how WordPress decides what template to use.

Using functions.php

Unlike style.css, the functions.php of a child theme does not override its counterpart from the parent. Instead, it is loaded in addition to the parent’s functions.php. (Specifically, it is loaded right before the parent’s file.)

In that way, the functions.php of a child theme provides a smart, trouble-free method of modifying the functionality of a parent theme. Say that you want to add a PHP function to your theme. The fastest way would be to open its functions.php file and put the function there. But that’s not smart: The next time your theme is updated, your function will disappear. But there is an alternative way which is the smart way: you can create a child theme, add a functions.php file in it, and add your function to that file. The function will do the exact same job from there too, with the advantage that it will not be affected by future updates of the parent theme. Do not copy the full content of functions.php of the parent theme into functions.php in the child theme.

The structure of functions.php is simple: An opening PHP tag at the top, and below it, your bits of PHP. In it you can put as many or as few functions as you wish. The example below shows an elementary functions.php file that does one simple thing: Adds a favicon link to the head element of HTML pages.

<?php // Opening PHP tag - nothing should be before this, not even whitespace

// Custom Function to Include
function favicon_link() {
    echo '<link rel="shortcut icon" type="image/x-icon" href="/favicon.ico" />' . "\n";
}
add_action( 'wp_head', 'favicon_link' );

TIP FOR THEME DEVELOPERS. The fact that a child theme’s functions.php is loaded first means that you can make the user functions of your theme pluggable —that is, replaceable by a child theme— by declaring them conditionally. E.g.:

if ( ! function_exists( 'theme_special_nav' ) ) {
    function theme_special_nav() {
        //  Do something.
    }
}

In that way, a child theme can replace a PHP function of the parent by simply declaring it beforehand.

Referencing / Including Files in Your Child Theme

When you need to include files that reside within your child theme's directory structure, you will use get_stylesheet_directory(). Because the parent template's style.css is replaced by your child theme's style.css, and your style.css resides in the root of your child theme's subdirectory, get_stylesheet_directory() points to your child theme's directory (not the parent theme's directory).

Here's an example, using require_once, that shows how you can use get_stylesheet_directory when referencing a file stored within your child theme's directory structure.

require_once( get_stylesheet_directory() . '/my_included_file.php' );

Other Useful Information

Using Post Formats

A child theme inherits post formats as defined by the parent theme. When creating child themes, be aware that using add_theme_support('post-formats') will override the formats defined by the parent theme, not add to it.

RTL support

To support RTL languages, add rtl.css file to your child theme, containing:

/*
Theme Name: Twenty Fourteen Child
Template: twentyfourteen
*/

rtl.css is only loaded by WordPress if is_rtl() returns true.

It's recommended to add the rtl.css file to your child theme even if the parent theme has no rtl.css file.

Internationalization

Child themes, much like other extensions, may be translated into other languages by using gettext functions. For an overview, please see Translating WordPress & I18n for WordPress Developers.

To internationalize a child theme follow these steps:

  • Add a languages directory.
    • Something like my-theme/languages/.
  • Add language files.
    • Your filenames have to be he_IL.po & he_IL.mo (depending on your language), unlike plugin files which are domain-he_IL.xx.
  • Load a textdomain.
    • Use load_child_theme_textdomain() in functions.php during the after_setup_theme action.
    • The text domain defined in load_child_theme_textdomain() should be used to translate all strings in the child theme.
  • Use GetText functions to add i18n support for your strings.

Example: textdomain

<?php
/**
 * Setup My Child Theme's textdomain.
 *
 * Declare textdomain for this child theme.
 * Translations can be filed in the /languages/ directory.
 */
function my_child_theme_setup() {
    load_child_theme_textdomain( 'my-child-theme', get_stylesheet_directory() . '/languages' );
}
add_action( 'after_setup_theme', 'my_child_theme_setup' );
?>

Example: gettext functions

<?php
_e( 'Code is Poetry', 'my-child-theme' );
?>


To sum up, all strings that use "my-child-theme" textdomain will be translatable. The translation files must reside in "/languages/" directory.

Resources

Be aware that some of these resources recommend using @import from your child theme's stylesheet as the method of importing the parent theme stylesheet. Please use the wp_enqueue_script() method described above.