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 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 best, 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.

Contents

Why use a Child Theme?

Here are a few reasons:

  • If you modify an existing theme and it is updated, your changes will be lost. With a child theme, you can update the parent theme (which might be important for security or functionality) and still keep your changes.
  • It can speed up development time.
  • It’s a great way to get started if you are just learning WordPress theme development.

How to Create a Child Theme

  • Child Theme directory structure
    Create a directory in your themes directory to hold the child theme. The theme directory is wp-content/themes. You should name the directory without any space as part of the name, and it is common practice to use the name of the parent theme folder with “-child” appended to it. For example, if you are making a child of the twentyfourteen theme, your folder name would be twentyfourteen-child.

Note: In this example, we are naming the child theme folder with “-child” appended to it for didactical purposes, but you can name the folder whatever you like as long as you include the line "Template:" on your child theme CSS, as will be explained below.

  • In the child theme directory, create a file called style.css. This is the only file required to make a child theme. The style sheet must start with the following lines:
/*
 Theme Name:   Twenty Fourteen Child
 Theme URI:    http://example.com/twenty-fourteen-child/
 Description:  Twenty Fourteen Child Theme
 Author:       John Doe
 Author URI:   http://example.com
 Template:     twentyfourteen
 Version:      1.0.0
 Tags:         light, dark, two-columns, right-sidebar, responsive-layout, accessibility-ready
 Text Domain:  twenty-fourteen-child
*/


@import url("../twentyfourteen/style.css");


/* =Theme customization starts here
-------------------------------------------------------------- */

You can change each of these lines to suit your theme. The only required lines are the Theme Name, the Template.

The Template is the directory name of the parent theme. In this case, the parent theme is the Twenty Fourteen theme, so the Template is twentyfourteen, which is the name of the directory where the Twenty Fourteen theme resides. If you want to make a child of a theme with the directory name example-theme-name, then you would use Template: example-theme-name.

Likewise, in the @import url line, twentyfourteen should be replaced with the name of your parent theme if you wish to import the parent's stylesheet, and you're using a theme that does not use wp_enqueue_style() in its functions.php file.

Note: The child theme’s stylesheet is included after the parent theme's and styles will therefore override those in the parent theme’s stylesheet.

(If your wordpress is running in multi-site mode, you may need to switch to the network admin dashboard, then themes, then click network enable. Then you switch to regular admin dashboard and the above step to activate your child theme should be present)

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

@import url("../twentyfourteen/rtl.css");

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.

Using wp_enqueue_style instead of @import

The benefit of using wp_enqueue_style() over @import is that enqueued stylesheets are all referenced from the HTML output to the browser, whereas an @import statement is referenced from the main stylesheet, which is an extra step before the browser knows where to look next.

In order to use this, both the parent and the child theme must call their respective enqueues in their respective functions.php.

The parent theme should then not include its stylesheet in any manual way.

To queue the parent stylesheet from its functions.php:

add_action( 'wp_enqueue_scripts', 'load_my_styles' );
function load_my_styles() {
    wp_enqueue_style( 'parent-theme', get_template_directory_uri() . '/style.css' );
}

To queue the child stylesheet from its functions.php:

add_action( 'wp_enqueue_scripts', 'load_my_child_styles', 20 );
function load_my_child_styles() {
    wp_enqueue_style( 'child-theme', get_stylesheet_uri() );
}

These identifiers are not meaningful in anyway other than that they get included in the HTML as ids. The text "-css" is added after these names.

Alternatively, if your parent theme does not use wp_enqueue_style() you can override its header.php, and do the enqueueing yourself. But you must enqueue both and in the right order, because your child CSS file must be last. Otherwise, it cannot override the parent CSS. However, your child functions.php will execute first. Therefore you must give it a lower priority (such as 20) than the default, so it gets executed last. If you do both yourself, you can simply call them in the right order (first enqueue the style of the parent, then of the child).

Resources