Ahosting Logo
Knowledge Base

How to Create a WordPress Child Theme

Two files, and the line that breaks itstyle.css· a header comment· with a Template line· naming the parent folder exactlyfunctions.php· enqueues the parent stylesheet· and holds your own codeThe line that breaks itTemplate must match the parent folder name exactly, including case. A near-miss produces a themethat activates and shows nothing.

A child theme is a small theme that inherits everything from another one. You edit the child; the parent stays untouched and can be updated without losing your work.

That is the entire point. Edit a theme directly and the next update overwrites your changes, not sometimes, every time, and usually months later when nobody connects the two events.

When you need one

You need a child theme if you are editing template files, changing the layout of a post, altering the header, adding functionality to functions.php.

You do not need one for CSS alone. WordPress has Additional CSS under Appearance → Customize, and it survives theme updates. For colour and spacing adjustments that is simpler and does the same job.

You also do not need one if your theme has a proper settings panel that does what you want. A child theme is for changes the theme does not offer.

Creating one: two files

In wp-content/themes/, create a folder. Name it after the parent with -child appended: twentytwentyfour-child.

Inside it, create style.css starting with a comment block:

/*
Theme Name: Twenty Twenty-Four Child
Template: twentytwentyfour
*/

Template is the important line, and it must be the parent's folder name exactly, not its display name, and it is case-sensitive. Getting this wrong is the single most common reason a child theme does not appear, or appears and breaks the site.

Then create functions.php:

<?php
add_action('wp_enqueue_scripts', function () {
 wp_enqueue_style('parent-style',
 get_template_directory_uri() . '/style.css');
});

That loads the parent's stylesheet. Without it the site loses all of its styling, which looks catastrophic and is a two-line fix.

Activate it under Appearance → Themes. The site should look identical to before. If it does not, that stylesheet line is where to look.

get_template_directory or get_stylesheet_directory

These two are the source of most child-theme confusion, and the rule is short.

get_template_directory() points at the parent.

get_stylesheet_directory() points at the child.

Use the first for the parent's assets and the second for your own. Mixing them produces files that load in development and not in production, or the reverse, with no obvious cause.

Overriding a template

Copy the file from the parent into the child, keeping the same path, then edit the copy. WordPress uses the child's version.

Copy from the parent rather than writing from scratch. You want the parent's version as the starting point so your change is small and readable.

Copy only what you are changing. Every file you copy stops receiving parent updates, so a child theme with twenty copied templates has twenty files that will silently fall behind. Copy one, change one.

functions.php works differently from templates

This is the exception, and it catches people who learned the copy-and-edit rule first.

A child's functions.php does not replace the parent's. Both run, with the child's loading first.

So never copy the parent's functions.php into the child: every function would then be declared twice and the site returns a fatal error. Add only what you want to add.

To change something the parent defines, use remove_action or remove_filter to detach it, then add your own. If the parent wrapped its function in function_exists, you can define your own version and yours wins.

Block themes work the same way

Modern block themes support child themes on the same principle, with a few extra files.

theme.json in the child merges with the parent's rather than replacing it, so you define only the values you are changing.

Templates live in templates/ and parts in parts/. Copy a file into the matching folder in the child to override it, exactly as before.

What a child theme does not protect

Worth being clear about, because people over-trust it.

Changes made in the Customizer or a page builder are stored in the database, not in the theme. They do not belong to the child theme and are not protected by it, and switching themes loses many of them.

Content is not protected either. A child theme protects the code you wrote in theme files, and nothing else, managing WordPress backups is what covers the rest.

If the parent theme is abandoned

A child theme is worth nothing if the parent stops receiving updates. You are then running unmaintained code with a small layer of your own on top.

Check that the parent is actively maintained before building on it. A theme last updated three years ago is a migration you have not scheduled yet.

Testing

Activate the child on a staging copy first, not on the live site. Setting up a WordPress staging site sets out making one.

Then check the pages that use different templates: a single post, an archive, a page, and search results. A missing Template line or a mistyped filename breaks one of those and leaves the others working, which is exactly the sort of fault that ships to production unnoticed.

If you are still choosing the parent, How to Choose and Install a WordPress Theme deals with what to look for before building on it.

Templates and styling belong in a child theme; loose snippets mostly do not. How to Use MU-Plugins and a Site-Specific Plugin sets out where they should live instead.

Check it is actually loading both stylesheets

A child theme that is active and not loading the parent's styling produces a site that looks broken in a way people blame on the theme.

curl -s https://example.com/ | grep -oE 'href="[^"]*themes/[^"]*\.css[^"]*"' | head
wp option get template; wp option get stylesheet

Both a parent and a child stylesheet should appear, in that order. Only one means the enqueue is wrong, and the fix is in the child's functions file rather than anywhere else.

The two options tell you which theme is the parent and which is active. When they are identical, the child is not active at all, whatever the appearance screen shows.

Copy the template, do not rewrite it

Overriding a template works by matching the parent's file path exactly, and small mistakes produce a file that is simply never used.

ls wp-content/themes/parent/template-parts/
diff wp-content/themes/parent/single.php wp-content/themes/child/single.php | head -20

Copy the original and edit the copy. Writing a replacement from scratch loses the hooks other plugins rely on, and those failures appear later in unrelated places.

Keep the diff small and readable. A child template that differs from its parent by three lines can be reconciled after a parent update in minutes; one rewritten entirely has to be rebuilt each time, which is the situation child themes exist to avoid.

Reconcile after every parent update

The child protects your changes from being overwritten. It does not keep them correct when the thing underneath changes.

wp theme update parent --dry-run
diff -r wp-content/themes/parent wp-content/themes/child 2>/dev/null | grep '^Only in.*child' | head

After a parent update, check every file you overrode against the new original. A template that referenced a function the parent has removed produces a fatal error on exactly the pages it controls.

Doing this on a copy first is the whole reason a staging site earns its keep, since the failure is on the front end and immediate. Setting up a staging site covers the copy.