Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 68 ยท Classic Themes and the Template Hierarchy

Child Themes

Learn what a WordPress child theme is, how the Template header links it to its parent, how files and functions are overridden, and when to skip it.

You install a theme, then want to change one thing: a footer line, a template, a color. If you edit the theme's files directly, the next theme update erases your work. A child theme solves this. It is a small theme that names another theme as its parent, and WordPress combines the two. Anything the child provides wins, and everything else comes from the parent. You can customize freely, and the parent keeps receiving updates.

In this lesson you will learn how to create a child theme, why you must enqueue the parent stylesheet yourself in a classic theme, how templates and functions are overridden, which parts of a parent are designed to be replaced, and when a child theme is not the right tool. The runnable example resolves files child-first and parent-second in plain PHP, because WordPress cannot run on this site; real WordPress code in code blocks is read-only.

This builds on Your First Classic Theme and Template Parts and Template Tags.

When to use a child theme

A child theme is a good fit when you:

  • use a third-party theme and want custom templates or code that survives updates,
  • change markup in a handful of files rather than rebuilding the whole design,
  • want to add features through functions.php on top of a parent.

It is a poor fit when you are writing the original theme, when you only need to change colors and fonts (a block theme's Site Editor and theme.json handle that, as covered later), or when you would replace almost every file. In that last case the parent adds weight and confusion, so you are better off forking it into a standalone theme. Small tweaks that are unrelated to appearance (a function, a filter) often belong in a plugin, so they survive a theme switch.

The smallest child theme

A child theme is a folder in wp-content/themes/ with at least a style.css file. Suppose the parent is a theme whose folder is acme-parent:

CSS
/*
Theme Name:   Acme Child
Theme URI:    https://example.com/acme-child
Description:  Customizations for Acme Parent
Author:       Your Name
Template:     acme-parent
Version:      1.0.0
Text Domain:  acme-child
*/

The key line is Template:. Its value is the folder name of the parent theme (not its display name). WordPress uses it to find the parent. Once the folder is in place, the child shows up in Appearance > Themes, and you activate the child, not the parent.

Two function families tell the two themes apart. This matters whenever you build a path or URL:

Function Points to
get_template_directory() / get_template_directory_uri() the parent theme
get_stylesheet_directory() / get_stylesheet_directory_uri() the active theme (the child)
get_theme_file_path( 'x' ) / get_theme_file_uri( 'x' ) the child's copy if it exists, otherwise the parent's

The names are confusing, and a good way to remember is that "template" is the parent and "stylesheet" is whichever theme owns the active style sheet. The get_theme_file_* pair is usually the most convenient, because it implements the child-first rule for you.

Loading the parent's styles

In a classic theme, the child's style.css is not a replacement for the parent's. WordPress does not import the parent stylesheet automatically, so you load it in functions.php:

PHP
function acme_child_styles(): void {
    $parent = wp_get_theme( get_template() );

    wp_enqueue_style(
        'acme-parent-style',
        get_template_directory_uri() . '/style.css',
        [],
        $parent->get( 'Version' )
    );

    wp_enqueue_style(
        'acme-child-style',
        get_stylesheet_uri(),
        [ 'acme-parent-style' ],
        wp_get_theme()->get( 'Version' )
    );
}
add_action( 'wp_enqueue_scripts', 'acme_child_styles' );

The child declares the parent as a dependency, so the child's rules come later and win when selectors are equal. Some parents build their CSS in other files (a compiled assets/css/main.css) and print them under their own handles. In that case, the parent already enqueues its own styles and you only need your own file. Read the parent's functions.php first. This is the same mechanism you saw in Enqueuing Styles and Scripts. Older tutorials suggest @import url( ../parent/style.css ) in the child's CSS; it works, but it is slower because the browser must discover the second file after loading the first.

Overriding templates

WordPress looks for each template file in the child first and then in the parent. To change footer.php, copy it from the parent into the child folder (same relative path) and edit your copy. Template hierarchy files such as single.php, archive.php, header.php and template parts loaded through get_template_part() all follow this rule.

TEXT
wp-content/themes/
  acme-parent/
    header.php
    footer.php
    single.php
    template-parts/content.php
  acme-child/
    style.css
    functions.php
    footer.php                  <- replaces the parent's footer
    template-parts/content.php  <- replaces the parent's part

Keep overrides small. When the parent updates, your copied file does not, so if the parent fixes a bug or changes markup, your copy is stuck with the old version. Prefer overriding template parts and small files over whole page templates, and look for hooks and filters in the parent before copying a file.

One file behaves differently: functions.php is not overridden, it is added. WordPress loads the child's functions.php first and then the parent's. Both run. This is why you must not copy the parent's functions.php into the child; the functions would be defined twice and PHP would stop with a "cannot redeclare" fatal error.

Overriding functions and hooks

Because the child's functions.php runs before the parent's, a child cannot simply redefine a function that the parent defines unconditionally. There are three supported routes:

  1. Pluggable functions. A well-written parent wraps overridable functions in a guard. Because the child loaded first, its version exists, and the guard skips the parent's:

    PHP
    // parent functions.php
    if ( ! function_exists( 'acme_posted_on' ) ) {
        function acme_posted_on(): void {
            echo esc_html( get_the_date() );
        }
    }
    
    // child functions.php (loads first)
    function acme_posted_on(): void {
        echo esc_html( 'Published ' . get_the_date() );
    }
    
  2. Filters. If the parent passes output through apply_filters(), change it with add_filter(). This is the most robust route and is covered in Actions and Filters.

  3. Removing parent hooks. Use remove_action() or remove_filter() with the same callback and priority, on a hook that runs after the parent has added its own, such as after_setup_theme at a later priority or init. Calling remove_action() directly at the top of the child's functions.php fails because the parent has not hooked anything yet.

PHP
add_action( 'after_setup_theme', function (): void {
    remove_action( 'wp_head', 'acme_parent_meta_tags' );
}, 20 );

The parent declares such hooks at its own priority (the default is 10), so priority 20 runs after it. Hook priorities and removal get their own lesson later in the track.

Resolving a file the way WordPress does

Here is the lookup logic as plain PHP. A virtual folder tree stands in for the two themes, and the function returns the first match, child first.

PHP Child-then-parent file lookup (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

footer.php and the content part come from the child, while the header, the single template and the meta part come from the parent. sidebar.php exists in neither, so WordPress would move on to its next candidate in the template hierarchy. The pluggable function prints the child's version because PHP defines the unguarded one first, which is the same effect you get in real WordPress.

flowchart TD
    R["Template request:<br/>footer.php"] --> C{"Exists in<br/>child theme?"}
    C -- yes --> UC["Use the child's file"]
    C -- no --> P{"Exists in<br/>parent theme?"}
    P -- yes --> UP["Use the parent's file"]
    P -- no --> N["Not found:<br/>try next candidate"]

Every template lookup tries the child first and the parent second.

Child themes and block themes

Block themes work with child themes too, and the mechanism is similar: a style.css with a Template: header, plus any files you want to replace. Differences to know:

  • A child can ship its own theme.json, and its settings and styles are merged over the parent's, so you can change a palette or a font without touching templates.
  • HTML templates and template parts in the child replace the parent's files of the same name.
  • Many block themes also offer style variations (alternative styles/*.json files that the owner picks in the Site Editor). If the change you want is a different look, a variation (or the owner's own changes saved by the Site Editor) is often simpler than a child theme.
  • The rule about enqueuing the parent stylesheet is a classic-theme habit. Check how the parent loads its CSS before adding code for it.

You will meet these files in the block theme lessons that follow. For now, remember that a child theme is a classic and block-theme tool, but a style variation is only a block-theme tool.

Common mistakes

  • Wrong Template: value. It must match the parent's folder name exactly, including case.
  • Copying the parent's functions.php. Both files load, so functions get declared twice and PHP stops with a fatal error.
  • Using get_template_directory_uri() for child assets. That points to the parent, so use get_stylesheet_directory_uri() or get_theme_file_uri().
  • Copying whole templates for tiny changes. Look for a hook or a template part first.
  • Activating the parent. Activate the child, or none of your changes apply.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does the Template: header in a child theme's style.css contain?

    WordPress finds the parent through the folder name in the Template header, and the match must be exact.
  2. 2. Which statement about functions.php in a parent and child theme is true?

    functions.php is added, not replaced. The child's file runs first, which is why parent functions meant to be overridden are wrapped in function_exists().
  3. 3. Which function returns the URL of a file inside the active child theme?

    get_stylesheet_directory_uri() points at the active theme, which is the child. get_template_directory_uri() always points to the parent.
  4. 4. Why can calling remove_action() at the top of the child's functions.php fail to remove a parent hook?

    The child loads first. Remove the hook later, for example on after_setup_theme at a higher priority number, after the parent has added it.
  5. 5. When is a child theme probably not the right tool?

    Code that should survive switching themes belongs in a plugin, because a child theme's code is active only while that theme is.

Summary

  • A child theme is a folder with a style.css whose Template: header names the parent's folder; activate the child.
  • Files are looked up in the child first, then the parent. Copy only the files you really need to change.
  • functions.php is added to the parent's rather than replacing it, and the child's runs first.
  • In classic themes you enqueue the parent's stylesheet yourself, unless the parent already enqueues its own CSS.
  • Override behavior with pluggable functions, filters or late remove_action() calls, not by copying functions.php.
  • For block themes, a child can merge a theme.json, and style variations are often a lighter option.

Next, learn the mechanism behind all of this extensibility in Actions and Filters.