How to create a WordPress child theme

A child theme inherits the design and functionality of an installed parent theme while keeping custom files separate. This lets the parent receive updates without automatically replacing changes made in the child theme.

Why create a child theme?

The source article used a simple example: changing the background color in Twenty Twelve’s parent style.css would work until a theme update replaced that file. Moving the customization into a child theme keeps the parent updateable and the custom code separate.

Suppose you change a background color by editing wp-content/themes/twentytwelve/style.css. A later Twenty Twelve update can replace that stylesheet. The same change stored in a child theme remains separate from the updated parent files.

Before you begin

• Confirm the parent theme is installed and identify its exact folder name.
• Create a full backup and use a local or staging environment.
• Document current menus, widgets, templates, styles, and Customizer or Site Editor changes.
• Use a code editor that can identify PHP, CSS, and JSON syntax errors.
• Keep the child theme in version control when it contains production code.
• Prepare a tested rollback before activating the child theme on a live site.

Create the child theme step by step

Example child-theme structure

A minimal child theme may contain only style.css. The other files are optional and should be added deliberately rather than copied automatically from the parent.

Create the style.css header

The original article included a complete metadata block and an @import rule. Keep useful metadata, but remove the old import. A current minimal example is:

/*
Theme Name: Parent Theme Child
Description: Update-safe customizations for Parent Theme.
Author: Your Name
Template: parenttheme
Version: 1.0.0
Text Domain: parenttheme-child
*/

Load the child stylesheet correctly

There is no single enqueue snippet that fits every parent theme. First inspect how the parent loads CSS:

• If the parent already loads both its own and the child stylesheet, add nothing.
• If the parent loads only its own stylesheet, enqueue the child stylesheet.
• If the parent uses get_stylesheet_uri(), it may already load the active child stylesheet and require the parent stylesheet to be added separately.
• A block theme may use theme.json and per-block styles instead of loading a traditional main stylesheet.

Load the child style.css

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

Load a separate child stylesheet

<?php
function tdwp_child_enqueue_custom_file() {
    $relative_path = 'assets/css/custom.css';
    $file_path     = get_theme_file_path( $relative_path );

    wp_enqueue_style(
        'tdwp-child-custom',
        get_theme_file_uri( $relative_path ),
        array(),
        file_exists( $file_path ) ? filemtime( $file_path ) : null
    );
}
add_action( 'wp_enqueue_scripts', 'tdwp_child_enqueue_custom_file' );

Use unique, prefixed handles. During development, a file modification time can help invalidate cached CSS. A production build may use a release version or asset manifest instead.

Why the old @import method was removed

Do not paste an enqueue snippet without checking the parent theme. Loading the same parent stylesheet twice can create duplicate requests and make the cascade harder to understand.

Understand how functions.php works

A template file in the child theme may replace the matching parent template, but functions.php behaves differently. WordPress loads the child file and the parent file, with the child loaded first.

• Do not copy the entire parent functions.php into the child.
• Duplicate function declarations can cause fatal errors.
• Use hooks and filters instead of rewriting parent functions whenever possible.
• Prefix custom functions, classes, constants, hooks, and asset handles.
• Move theme-independent business functionality into a plugin.

Include a helper file from the active theme

<?php
$helper_file = get_theme_file_path( 'inc/helpers.php' );

if ( file_exists( $helper_file ) ) {
    require_once $helper_file;
}

get_theme_file_path() checks the child theme first when a child is active, then falls back to the parent when the file does not exist in the child.

Override templates, parts, and patterns

To replace a supported parent file, copy only that file into the matching location in the child theme, preserve its filename and relative folder structure, and then make the required changes.

Create a child theme for a block theme

The same required style.css relationship applies, but a block-theme child may rely more heavily on theme.json, HTML templates, template parts, patterns, style variations, and the Site Editor than on traditional PHP templates.

Minimal child theme.json

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "styles": {
    "color": {
      "background": "#ffffff",
      "text": "#182033"
    },
    "elements": {
      "button": {
        "border": {
          "radius": "0.5rem"
        }
      }
    }
  }
}

WordPress combines settings and styles from core, the parent, the child, and user customizations. The child can override selected parent values without copying the entire parent theme.json.

Account for Site Editor customizations

Templates, template parts, and styles saved through the Site Editor are stored in the database and may override files in the child theme. Before assuming a file is ignored, check whether a customized version exists in the editor and review the available reset or clear-customization controls.

Add an optional screenshot

A screenshot.png file helps identify the child theme on the Themes screen. It is optional for a private project. Use an original image that represents the customized theme and avoid copying protected promotional artwork without permission.

Install and activate the child theme

1. Keep the parent installed. The child cannot operate without its declared parent theme.
2. Create a ZIP of the child folder. The archive should contain the child files inside one top-level folder.
3. Upload the ZIP. Go to Appearance > Themes > Add New > Upload Theme.
4. Install and preview. Use a staging site or live preview when available.
5. Activate the child. Confirm the site still renders before continuing customization.

Activation may change the active theme record even though the child inherits the parent. Recheck menus, widgets, Customizer settings, Site Editor templates, logo assignments, and plugin integrations after activation.

Test before and after activation

Troubleshooting common child-theme problems

The child theme does not appear

Check that style.css is in the root of the child folder and contains a readable theme header. Confirm the ZIP did not introduce an extra nested folder.

WordPress says the parent theme is missing

Install the parent and verify that Template exactly matches its directory name. Do not use the parent’s marketing name or a path such as wp-content/themes/parenttheme.

The child stylesheet does not load

Inspect the page source and network panel, then review the parent theme’s enqueue logic. Add the child stylesheet only when it is not already loaded.

The parent design disappears

The parent may load only the active theme’s style.css. In that configuration, activating the child replaces the loaded stylesheet URL. Review the parent code and enqueue its stylesheet correctly before the child stylesheet.

A copied template has no effect

Confirm the exact filename, folder, template hierarchy, and active theme. For block themes, check whether a database-saved Site Editor template overrides the file.

A PHP customization causes a fatal error

Restore the previous file through hosting access or version control. Check syntax, duplicate function names, missing dependencies, hook timing, and PHP compatibility.

Changes vanish after switching themes

Child-theme files remain on disk, but theme-specific settings and active styling may not apply while another theme is active. Functionality that must remain across themes belongs in a plugin.

Security and maintenance

• Do not download a generated child theme from an untrusted service and install it without reviewing the files.
• Validate and escape data used by child-theme PHP customizations.
• Keep the parent theme installed and updated because the child inherits its code.
• Remove unused templates, libraries, and copied files.
• Review child overrides whenever the parent releases template or API changes.
• Keep backups, version history, and deployment records.
• Test current WordPress, PHP, browser, and plugin compatibility in staging.

What changed from the original 2013 guide

The original page explained why child themes protect customizations, created a folder and style.css, imported the parent stylesheet, copied matching template files, and activated the child. The revised guide keeps that foundation while replacing @import, explaining parent enqueue differences, documenting functions.php behavior, adding block-theme and theme.json support, and expanding installation, testing, accessibility, security, and maintenance guidance.

Related TDWP guide

After the child theme is working, use How to Add Custom CSS to a WordPress Theme to choose between a stylesheet, Additional CSS, block-level CSS, and dynamic styles.

Official WordPress references