Codex tools: Log in
Languages: English • 日本語 • 한국어 • Français • Português do Brasil • Русский • Slovenčina • ไทย • 中文(简体) • (Add your language)
A WordPress child theme is a theme that inherits the functionality of another theme, called the parent theme, and allows you to modify, or add to, the functionality of that parent theme. This article shows how to create a basic child theme and explains what you can do with it. As an example parent theme it uses Twenty Eleven, the new default theme in WordPress 3.0.
Making a child theme is very simple. Create a directory, put a properly formatted style.css file in it, and you have a child theme! With a little understanding of HTML and CSS, you can make that very basic child theme modify the styling and layout of a parent theme to any extent without editing the files of the parent theme itself. That way, when the parent theme is updated, your modifications are preserved.
For this reason, child themes are the recommended way of making modifications to a theme.
With a basic understanding of PHP, WordPress Templates, and the WordPress Plugin API, you can make the child theme extend virtually every aspect of a parent theme, and again, without actually changing the parent theme files.
Contents |
A child theme resides in its own directory in wp-content/themes. The scheme below shows the location of a child theme along with its parent theme (Twenty Eleven) in a typical WordPress directory structure:
This directory can contain as little as a style.css file, and as much as any full-fledged WordPress theme contains:
Let’s see how each of these works.
style.css is the one and only required file in a child theme. It provides the information header by which WordPress recognizes the child theme, and it replaces the style.css of the parent.
As with any WordPress theme, the information header must be at the top of the file, the only difference being that in a child theme the Template: line is required, so that WordPress knows which theme is the parent of the child theme.
Here is an example information header of a child theme’s style.css:
/* Theme Name: Twenty Eleven Child Theme URI: http://example.com/ Description: Child theme for the Twenty Eleven theme Author: Your name here Author URI: http://example.com/about/ Template: twentyeleven Version: 0.1.0 */
A quick explanation of each line:
Theme Name. (required) Child theme name.
Theme URI. (optional) Child theme webpage.
Description. (optional) What this theme is. E.g.: My first child theme. Hurrah!
Author URI. (optional) Author webpage.
Author. (optional) Author name.
Template. (required) directory name of parent theme, case-sensitive.
Version. (optional) Child theme version. E.g.: 0.1, 1.0, etc.
The part after the closing */ of the header works as a regular stylesheet file. It is where you put the styling rules you want WordPress to apply.
Note that a child theme’s stylesheet replaces the stylesheet of the parent completely. (The parent’s stylesheet is not loaded at all by WordPress.) So, if you simply want to modify a few small things in the styling and layout of the parent —rather than make something new from scratch— you have to import explicitly the stylesheet of the parent, and then add your modifications. The following example shows how to use the @import rule to do that.
Our parent theme for this example is Twenty Eleven. We like most everything about it, except the color of the site’s title, which we want to change from black to green. Using a child theme, all it takes is three simple steps:
/*
Theme Name: Twentyeleven Child
Description: Child theme for the twentyeleven theme
Author: Your name here
Template: twentyeleven
*/
@import url("../twentyeleven/style.css");
#site-title a {
color: #009900;
}
Here is what the above code does, step by step:
/* opens the child theme’s information header.
Theme Name: declares the child theme’s name.
Description: describes what the theme is. (Optional; can be omitted.)
Author: declares the author’s name. (Optional; can be omitted.)
Template: declares the child theme’s parent; i.e., the directory of the theme whose templates the child uses.
*/ closes the child’s information header.
@import rule brings in the parent’s stylesheet.
#site-title a rule defines a colour (green) for the site’s name, overriding the corresponding rule of the parent.
@import rule There must be no other CSS rules above the @import rule. If you put other rules above it, it will be invalidated and the stylesheet of the parent will not be imported.
To support RTL languages, add rtl.css file to your child theme, containing:
/*
Theme Name: Twenty Eleven Child
Template: twentyeleven
*/
@import url("../twentyeleven/rtl.css");
WordPress auto-loading rtl.css file only if is_rtl(). Even if the parent theme has no rtl.css file, it's recommended to add the rtl.css file to your child theme.
The twenty eleven dark theme stylesheet and the link color option are loaded after the child theme stylesheet, therefore some color changes might not show as they are loaded earlier.
There is no need to change the dark stylesheet or code in the twenty eleven parent directory, as we can correct this by giving our color change priority, we do this by adding !important to the style.
Here we will change the Site Title color, and the negate the Site Title hover color, if we did not like the title color or it being shown as a link.
/*
Theme Name: Twenty Eleven Child
Description: Child theme for the Twenty Eleven theme
Author: Your name here
Template: twentyeleven
*/
@import url("../twentyeleven/style.css");
/* This will override site title color even on the dark theme */
#site-title a {
color: #009900 !important;
}
/* This will override the changed link color */
#site-title a:focus,
#site-title a:hover,
#site-title a:active {
color: #009900 !important;
}
The selected style colors with the !important will now not be changed by the dark stylesheet or the link color option.
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.
The structure of functions.php is simple: An opening PHP tag at the top, a closing PHP tag at the bottom, and, between them, 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.
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 again.
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' );
A child theme inherits post formats as defined by the parent theme. But, when creating child themes, be aware that using add_theme_support('post-formats') will override the formats as defined by the parent theme, not add to it.
Templates in a child theme behave just like style.css, in that they override their namesakes from the parent. A child theme can override any parental template by simply using a file with the same name. (NOTE. index.php can be overriden only in WordPress 3.0 and newer.)
Again, this WordPress feature lets you modify the templates of a parent theme without actually editing them, so that your modifications are preserved when the parent theme is updated.
Here are a few example cases for using template files in a child theme:
In addition to style.css, functions.php, and to template files like index.php, and home.php, a child theme can use any type of file full-fledged themes use, as long as that file is properly linked. For example, a child theme can use icons and images that are linked from its stylesheet, JavaScript files linked from the top or bottom of pages, or extra PHP files called from its templates or from its functions.php file.
