Creating a child theme

Module 5: Themes and plugins · Reading time: 9 minutes

Learning objective: After this lesson you can create a child theme, and you know when you need one and when you don't.

Key concepts: child theme, parent theme, Template: in style.css, functions.php, wp_enqueue_style, overriding a template, theme.json in a child, Create Block Theme

The problem a child theme solves

Say you want the header of your classic theme to look slightly different, and you change header.php in the theme folder to do it. It works. Three weeks later the theme gets an update, which you let install automatically (as it should, lesson 7.2). The update replaces all the theme's files, and your change is gone.

A child theme is a small theme that says: "use everything from that other theme (the parent theme), except what I provide myself." You put your changes in the child theme. You keep updating the parent theme as normal, and your changes stay in place.

When you do and don't need one

You need a child theme if you want to change or add to a theme's files:

• you want a template (a PHP file for a classic theme, an HTML template for a block theme) to be different;
• you want custom CSS that's too large for the CSS box;
• you want custom PHP code that belongs to the design (an extra image size, an extra menu location).

You don't need a child theme if:

• you're customising a block theme in the Site Editor: those changes are stored in the database and survive an update (lesson 5.1);
• you're only adding a bit of CSS via Additional CSS (in the Customiser for a classic theme, or under Styles in the Site Editor);
• you want to add a function that has nothing to do with the design (a form, an integration). That belongs in a plugin, so it survives a theme switch.

A child theme for a classic theme

A child theme is a folder in wp-content/themes/ with at least one file: style.css. Say your parent theme is in wp-content/themes/maintheme/. Then create a folder wp-content/themes/maintheme-child/ with this style.css:

/*
Theme Name:   Main Theme Child
Template:     maintheme
Description:  Custom changes for example.com
Version:      1.0.0
Text Domain:  maintheme-child
*/

/* Your own CSS goes below. */
.site-header { border-bottom: 3px solid #e8a33d; }

The most important line is Template:. It holds the name of the folder of the parent theme (not the name you see in the Dashboard). If it's not exactly right (capital letters, hyphens), WordPress will report at Appearance > Themes that the parent theme is missing.

You also create a functions.php file to load the stylesheets. The proper way to do this:

<?php
add_action( 'wp_enqueue_scripts', function () {
    wp_enqueue_style(
        'maintheme-child',
        get_stylesheet_uri(),
        array(),
        wp_get_theme()->get( 'Version' )
    );
} );

Whether the parent theme loads its own stylesheet varies by theme. Check your parent theme's documentation; some ask you to also load the parent's stylesheet in the child with get_template_directory_uri() . '/style.css'. If your website has no styling after activating the child, the parent's stylesheet isn't being loaded.

If you want to change a template, copy that single file (for example header.php) from the parent to your child and edit the copy. WordPress looks in the child first, then in the parent. Don't copy all the files: then you'll stop getting the parent's improvements.

The child's functions.php doesn't replace the parent's, but is loaded before it. Both are run.

A child theme for a block theme

For a block theme it works the same way, with block files:

• style.css with the same header and Template:;
• optionally your own theme.json: this is merged with the parent's, so you only include what you want to change (for example the colour palette);
• optionally templates in templates/ and parts/ that replace the parent's.

A functions.php file is often not needed for a block theme, because WordPress loads the styles from theme.json itself.

There's an official plugin, Create Block Theme, which creates a child theme for you straight from the Site Editor, including your changes from the database. Handy if you've customised a block theme in the Site Editor and want to capture those changes in files (for example to take them to another website).

How to set it up on your website

1. Create the folder and files on your own computer and check the parent theme's folder name.
2. Upload the folder to wp-content/themes/ using File Manager or via SFTP. Or zip the folder and upload it at Appearance > Themes > New Theme > Upload Theme.
3. Go to Appearance > Themes. Your child theme is listed there. Activate it.
4. Check your website: menus and widgets may need to be reassigned when switching to a child theme; Customiser settings apply per theme, so you'll need to set them again or export them with a plugin.
5. The parent theme must stay installed. Don't remove it; the child won't work without it.

It's best to do this in a staging site first (lesson 8.3), since switching themes on a busy live website can get messy for a moment.

Summary

• A child theme keeps your changes to theme files separate from the parent theme, so updates don't overwrite them.
• You don't need one for changes made in the Site Editor or a bit of Additional CSS; functions belong in a plugin.
• At minimum: a folder with style.css in which Template: states exactly the parent theme's folder name.
• Only copy the templates you genuinely change; the child's functions.php runs alongside the parent's.
• The parent theme stays installed and keeps getting updated.

Quiz

Exercise

Exercise A5.2: Check your child theme. Create a child theme for your theme, on your test website or in staging (lesson 8.3), and activate it. Enter the website's address and the child theme's folder name. The tool requests wp-content/themes/<folder>/style.css and checks: the file exists, it contains a Theme Name: and a Template:, the parent's style.css in that folder also exists, and the homepage refers to the child theme (so it's active).

Exercise D5.2: What have you changed, and why? Note down which files are in your child theme, what you changed in each file and why that couldn't be done in the Site Editor, in Additional CSS, or in a plugin. Confirm that the parent theme is still installed and has automatic updates enabled.

Further reading

These articles describe the steps in WebOké's control panels; in other control panels they work in a similar way.

• DirectAdmin guide 11.1: Opening File Manager: the directories in your package
• DirectAdmin guide 11.2: Uploading and downloading files
• DirectAdmin guide 11.7: Connecting with FileZilla (FTP, FTPS and SFTP)
• Child themes (developer.wordpress.org, English): https://developer.wordpress.org/themes/advanced-topics/child-themes/