- Themes » Create a Child Theme
- What is a Child Theme?
- Create a Child Theme
- Create a Child Theme Manually
- Create a Child Theme Using the Create Block Theme Plugin
- Create a Child Theme Using Child Theme Configurator
- Make Changes to Your Child Theme
- Developer Resources
- Child Themes
- What is a Parent Theme?
- What is a Child Theme?
- How to Create a Child Theme
- 1. Create a child theme folder
- 2. Create a stylesheet: style.css
- 3. Enqueue stylesheet
- 4. Install child theme
- 5. Activate child theme
- Adding Template Files
- Using functions.php
- Referencing or Including Other Files
- Enqueueing Styles and Scripts
- Special Considerations
- Post Formats
- RTL Support
- Example: textdomain
- Example: gettext functions
Themes » Create a Child Theme
This feature is available on sites with the WordPress.com Business or eCommerce plan. If your site has one of our legacy plans, it is available on the Pro plan.
You can make many changes to your theme’s appearance using custom CSS and build upon its default functionality using plugins. If you’d like to go further and make changes to your theme’s underlying code, then you could consider creating a child theme.
Please note that this is an advanced option that requires knowledge of HTML and PHP.
What is a Child Theme?
A child theme is a theme that inherits the functionality and styling of a parent theme.
To use an analogy from Kathryn Presner’s talk on Getting Comfortable with Child Themes: Think of a parent theme as a master recipe for brownies. You could create a child recipe called nutty brownies that inherits all of the ingredients and steps, but with the addition of nuts.
Below you’ll find screenshots of two themes in our repository, Bradford and Seedlet. Bradford is a child theme of Seedlet. You’ll see that Bradford inherits much of Seedlets’s design and has its own additional customizations:
Create a Child Theme
To use child themes with a WordPress.com site, you’ll need to first install WordPress locally on your computer. After you’ve created your child theme locally, you can then zip it up and upload it to your WordPress.com plugin-enabled site.
An alternative to manually creating your child theme is to make use of a plugin that will create your child theme for you (for example Child Theme Configurator or Create Block Theme – each of which is explained later in this guide.) Search the plugin repository for “child themes” to browse through more options.
Please note: You can download a copy of free themes in our collection at the bottom of each WordPress.com showcase page. Look for the download link:
It is not possible to create a child theme of a theme that is already the child of another theme.
Create a Child Theme Manually
For the example below, we’re going to be using the Twenty Seventeen theme.
- Search and download your theme file from the WordPress.org repository here. Once downloaded, double-click on a Mac, and that will extract the folder. Or if you’re on Windows, right-click and “Extract all.”
- Create a new folder and give your child theme a name, for example, ‘twentyseventeen-child’.
It is recommended that the name of your child theme directory is appended with ‘-child’. Make sure that there are no spaces in your child theme directory name.
- Copy and paste the style.css and functions.php files from your original parent theme (twentyseventeen) into your new child theme (twentyseventeen-child).
- In your new child theme, open up your style.css file using a text editor, such as Notepad, Atom, Sublime Text, or any other text editor of your choice. Empty the file by clicking command+A > delete on Mac (CTRL+A > delete on Windows).
Afterward, copy and paste the below lines of code:
Please note that the CSS code below may be theme-specific.
You need to change the following lines to include the parent folder name to show that this particular theme will be its child.
– Theme name
You should keep the following fields as they are:
– Text domain
The other fields are optional but not required. You can read more about what they are for here.
The template line should contain the folder name of your parent theme. Make sure to save this file after the changes have been made.
- In your new child theme, open up your functions.php file using the same text editor. Empty the file by clicking command+A > delete on Mac (CTRL+A > delete on Windows).
Afterward, copy and paste the below code and replace the ‘$parent-style’ value with the name of your theme with a -style added (in this case it’s twentyseventeen-style).
Make sure to save this file after the changes have been made.
- Now we need to zip up the folders:
- Locate the file or folder that you want to zip.
- Press and hold (or right-click) the file or folder, select (or point to) Send to, and then select Compressed (zipped) folder.
A new zipped folder with the same name is created in the same location. To rename it, press and hold (or right-click) the folder, select Rename, and then type the new name.
- Locate the items to zip in the Mac Finder (file system)
- Right-click on a file, folder, or files you want to zip.
- Select “Compress Items”
- Find the newly created .zip archive in the same directory.
- You can now upload the .zip file of your custom theme by going to Appearance → Themes and clicking the Upload Theme button. Upload both your parent theme and your child theme and activate your child theme.
Create a Child Theme Using the Create Block Theme Plugin
If you’re using a block editor theme, you can use the Create Block Theme plugin to create a new child theme with the currently active theme as the parent theme. This plugin makes it easier than ever to create a child theme right from within your site’s dashboard. Visit the Create Block Theme plugin to get started.
Create a Child Theme Using Child Theme Configurator
Please note that Child Theme Configurator is a third-party plugin and support for this plugin can be found and submitted here: https://wordpress.org/support/plugin/child-theme-configurator/
- Once installed go to Tools > Child themes. Select a parent theme.
- Hit Analyze. This checks that the parent themes are using WordPress standard practice and that there’ll be no surprises with your theme.
- This is the name of the directory/folder that is housing the theme in your site.
- Select where you’re saving your styles. It’s recommended that you select the default primary stylesheet style.css option
- Select the parent theme stylesheet handling option, this determines how your child theme will use the styles of your parent theme. It’s recommended that you use the WordPress style queue option.
- Customize the child theme name, description, author and version. This where you enter in your themes credentials that will appear in your style sheet CSS.
- Copy parent theme menus, widgets and customizer settings. If you’ve been setting up your parent theme in the Customizer, this option will copy over those settings into your new child theme.
Make Changes to Your Child Theme
We always recommend making changes to your theme away from your live site. Please see this guide on making changes locally.
A child theme allows you to change small aspects of your site’s appearance yet still preserve your theme’s look and functionality. To understand how child themes work it is first important to understand the relationship between parent and child themes.
What is a Parent Theme?
A parent theme is a complete theme which includes all of the required WordPress template files and assets for the theme to work. All themes – excluding child themes – are considered parent themes.
What is a Child Theme?
As indicated in the overview, a child theme inherits the look and feel of the parent theme and all of its functions, but can be used to make modifications to any part of the theme. In this way, customizations are kept separate from the parent theme’s files. Using a child theme lets you upgrade the parent theme without affecting the customizations you’ve made to your site.
- make your modifications portable and replicable;
- keep customization separate from parent theme functions;
- allow parent themes to be updated without destroying your modifications;
- allow you to take advantage of the effort and testing put into parent theme;
- save on development time since you are not recreating the wheel; and
- are a great way to start learning about theme development.
How to Create a Child Theme
1. Create a child theme folder
First, create a new folder in your themes directory, located at wp-content/themes .
The directory needs a name. It’s best practice to give a child theme the same name as the parent, but with -child appended to the end. For example, if you were making a child theme of twentyfifteen , then the directory would be named twentyfifteen-child .
2. Create a stylesheet: style.css
Next, you’ll need to create a stylesheet file named style.css , which will contain all of the CSS rules and declarations that control the look of your theme. Your stylesheet must contain the below required header comment at the very top of the file. This tells WordPress basic info about the theme, including the fact that it is a child theme with a particular parent.
The following information is required:
- Theme Name – needs to be unique to your theme
- Template – the name of the parent theme directory. 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.
Add remaining information as applicable. The only required child theme file is style.css, but functions.php is necessary to enqueue styles correctly (below).
3. Enqueue stylesheet
The final step is to enqueue the parent and child theme stylesheets, if needed.
Note: In the past, the common method was to import the parent theme stylesheet using @import inside style.css . This is no longer the recommended practice, as it increases the amount of time it takes style sheets to load. Plus it is possible for the parent stylesheet to get loaded twice.
The ideal way of enqueuing stylesheets is for the parent theme to load both (parent’s and child’s), but not all themes do this. Therefore, you need to examine the code of the parent theme to see what it does and to get the handle name that the parent theme uses. The handle is the first parameter of wp_enqueue_style() .
There are a few things to keep in mind:
- the child theme is loaded before the parent theme.
- everything is hooked to an action with a priority (default is 10) but the ones with the same priority run in the order they were loaded.
- for each handle, only the first call to wp_enqueue_style() is relevant (others ignored).
- the dependency parameter of wp_enqueue_style() affects the order of loading.
- without a version number, site visitors will get whatever their browser has cached, instead of the new version.
- using a function to get the theme’s version will return the active theme’s version (child if there is a child).
- the functions named get_stylesheet * look for a child theme first and then the parent.
The recommended way of enqueuing the stylesheets is to add a wp_enqueue_scripts action and use wp_enqueue_style() in your child theme’s functions.php .
If you do not have one, create a functions.php in your child theme’s directory. The first line of your child theme’s functions.php will be an opening PHP tag ( get_template , such as get_template_directory() and get_template_directory_uri() , the child theme needs to load just the child styles, using the parent’s handle in the dependency parameter.
If the parent theme loads its style using a function starting with get_stylesheet , such as get_stylesheet_directory() and get_stylesheet_directory_uri() , the child theme needs to load both parent and child stylesheets. Be sure to use the same handle name as the parent does for the parent styles.
4. Install child theme
Install the child theme as you install any other theme. You can copy the folder to the site using FTP, or create a zip file of the child theme folder, choosing the option to maintain folder structure, and click on Appearance > Themes > Add New to upload the zip file.
5. Activate child theme
Your child theme is now ready for activation. Log in to your site’s Administration Screen, and go to Administration Screen > 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 Screen to enable the theme (within the Network Admin Themes Screen tab). You can then switch back to your site-specific WordPress Administration Screen to activate your child theme.)
Note: You may need to re-save your menu from Appearance > Menus and theme options (including background and header images) after activating the child theme.
Adding Template Files
Other than the functions.php file (as noted above), any file you add to your child theme will overwrite the same file in the parent theme.
In most cases, it’s best to create a copy of the template files you want to change from the parent theme, then make your modifications to the copied files, leaving the parent files unchanged. For example, if you wanted to change the code of the parent theme’s header.php file, you would copy the file to your child theme folder and customize it there.
Tip: There are several plugins which allow you to detect what specific template is being used on the page at which you are looking.
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 (e.g. page-3.php would load for a Page with the ID of 3).
See the Template Hierarchy page for more information about how WordPress determines which template to use.
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.
Tip: 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.
In that way, a child theme can replace a PHP function of the parent by simply declaring it beforehand.
For more information about what to include in your child theme’s functions.php file, read through the Theme Functions page.
Referencing or Including Other Files
When you need to include files that reside within your child theme’s directory structure, you will need to use get_stylesheet_directory() . Since the style.css is 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). To reference the parent theme directory, you would use get_template_directory() instead.
Below is an example illustrating how to use get_stylesheet_directory() when referencing a file stored within the child theme directory:
Meanwhile, this example uses get_stylesheet_directory_uri() to display an image that is stored within the /images folder in the child theme directory.
Unlike get_stylesheet_directory() , which returns a file path, get_stylesheet_directory_uri() returns a URL, which is useful for front-end assets.
Enqueueing Styles and Scripts
WordPress won’t automatically load the stylesheet for your child theme on the front-end. Below is an example of using the wp_enqueue_scripts() action hook to call a function that enqueues the child theme’s stylesheet.
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.
To support RTL languages, add a rtl.css file to your child theme, containing:
Even if the parent theme does not have an rtl.css file, it’s recommended to add the rtl.css file to your child theme. WordPress will auto-load the rtl.css file only if is_rtl() is true.
Child themes can be prepared for translation into other languages by using the WordPress Internationalization API. There are special considerations regarding internationalization of child themes.
To internationalize a child theme follow these steps:
1. Add a languages directory.
- For example: twentyfifteen-child/languages/
2. 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 .
3. 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.
4. Use GetText functions to add i18n support for your strings.
At this point, strings in the child theme are ready for translation. To ensure they are properly internationalized for translation, each string needs to have the twentyfifteenchild textdomain.
Example: gettext functions
Here is an example of echoing the phrase “Code is Poetry”:
The text domain defined in load_child_theme_textdomain() should be used to translate all strings in the child theme. In the event that a template file from the parent them has been included, the textdomain should be changed from the one defined in the parent theme to the one defined by the child theme.