SCreenshot of Visual Studio code showing files in WordPress block theme

Let’s Make a Block Child Theme

How are block themes different from classic themes?

Quick Review

  • What is a child theme?
  • Why use one?

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 that 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?

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.

Child themes

  • 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
  • great way to start learning about theme development.

Block vs Classic Themes

  • Block themes are built for the newer functionality of WordPress
    • Use blocks to edit all parts of your site, customize everything from your background colors to font sizes for all heading blocks.
  • Classic themes are built with PHP templates, functions.php and more
    • Include features like widgets, a dedicated menus section, a customizer, and more.
  • Classic themes do not work with the Site Editor.

Building a child theme for a block theme.

  • Start with a testing environment.
    • LocalWP from WP Engine. Cross-platform local development environment for WordPress.
  • Download LocalWP at

LocalWP Default Setup

  • LocalWP sites start with 3 default themes. They are:
    • Twenty Twenty-Three << set as the active theme
    • Twenty Twenty-Two
    • Twenty Twenty-One
  • We are going to build a child theme for TwentyTwentyThree

Basic Local Site Environment

Site created -> http://letsmakeachildtheme.local

Screenshot of the LocalWP admin dashboard showing new local site name letsmakeachildtheme

We are going to use the LocalWP admin screen to jump to the folder on our PC that holds the newly built website. The “Go to site folder” link jumps right to the root of the local site.

Screenshot capture of PC file explorer showing folders and files in a local WordPress website.

Folder setup on disk with LocalWP. LocalWP creates the top-level folder on disk using the name of the website. Inside that is an ‘app/public/’ folder which holds the WordPress core files. LocalWP also creates a few support folders that hold the configuration data for the specific webserver and the PHP version being used for the website. We won’t be working with those folders and files here.

You have the WordPress website with folders

  • wp-admin, wp-content, wp-includes
  • 18 files created on a new site
  • The files created may vary based on your host

Block Theme Child Theme Requirements

  • Folder to hold child theme files
    • style.css
    • theme.json
  • 2 additional folders
    • parts
    • templates

I’m going to jump into my editor for this next step to better demonstrate the the folder and file creation steps in a more cross platform experience. I use Visual Studio Code as my code editor. It’s available for Windows, Mac, Linux, or on the web.

Open wp-content/themes folder in VS Code editor.

SCreenshot of Visual Studio code showing files in WordPress block theme

Create a folder for our child theme. We will call it mychildtheme.

Create two files & folders


The style.css file needs a few tags so that WordPress knows it is a theme, and that it is a child of a parent theme. By default, all themes are considered parent themes.

A theme.json file is used to define the many settings in Global Styles and more. You can learn more about theme.json from the developer handbook.

In Classic themes, functions.php is necessary for child themes. Block child themes do not require this. Let’s jump into the dashboard of our WordPress website to see what is going on.

The style.css file needs tags to show that it is a child theme. Basic tags needed are the theme name and the template name. They include the name of the parent theme. That name matches the theme folder name.


The developer documentation says:

Your stylesheet must contain the 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.

You’ll need to include the boilerplate in style.css file containing your header information.

  • Theme Name: the name of your new child theme.
  • Template Name: the folder (directory) name of the parent theme.
  • Text Domain: name is unique to your WordPress child theme.

A minimal child theme style.css file header is shown below:

Theme Name: My Child Theme
Template: twentytwentythree
Text Domain: twentytwentythree-child

Here is a full style.css header.

Theme Name: Twenty Twenty-Three Child
Theme URI:
Author: Your name
Author URI:
Description: Twenty Twenty Three Child Theme
Requires at least: 5.8
Tested up to: 6.1
Requires PHP: 5.6
Version: 0.1
License: GNU General Public License v2 or later
License URI:
Text Domain: twentytwentythree-child
Template: twentytwentythree


See the developer documentation for a deeper dive into theme.json. We’ll take a look at the Twenty Twenty-Three theme.json file at the highest level.

    "version": 2,
    "customTemplates": {},
    "settings": {},
    "styles": {},
    "templateParts": {}

Within each of these are further styles available to you. For example, the settings area in the Twenty TwentyThree uses:

    "settings": {
        "appearanceTools": true,
        "layout": {
            "contentSize": "650px",
            "wideSize": "1200px"
    "slug": "foreground-and-background",
    "name": "Foreground and background"

It is recommended that you copy the theme.json file from the parent theme and edit as needed. Take out the settings you do not intend to change and keep the ones you will tweak for your child theme.

If you are so inclinded, start from scratch.

For help making a theme.json file check out the site for a guide to creating many of the choices for your theme.json file.

Folders: parts & templates

  • parts folder holds customizable elements, ie headers and footers, built with html.
  • templates folder is where you will create customizable pages that used to be built using php template files.
    • Very similar to template files in classic theme
    • Built using Block editor-styled HTML elements

Let’s Make a Change & Create a Child Theme

My New Color pallet

Bluey Party Theme from

Block theme child theme generators do all this for you!

Child theme generators for block themes

Allows you to make changes in the current block theme, and then save those changes as a child that is downloaded and ready for you to install and activate.

Child theme generators for non-block themes

These will create 2-4 basic files needed for non-block themes. The WPS Child Theme Generator will also enable you to download a zip of the theme.


  • theme.json –

This presentation was delivered at the BurbsWP WordPress gathering held in person in Malvern, on November 14, 2022. Sponsored by Green Street Technology Solutions.

Similar Posts

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.