Clean, Simple but Powerful

How To Create WordPress Block Theme In 2024 | Quick & Easy Steps


Last Update: 20 Jan, 2025

Since Gutenberg became a big reality for full site editing, a lot of talking and discussion have been going on. As of Gutenberg 7.2.0 version, the block template has been an experimental feature. Now, things have changed, and using block templates to create block-based themes has become an exploratory stage of WordPress development.

So, the question arises – “How to create WordPress block theme?” Don’t worry, we are going to answer this question in the most convenient way possible so that you can create a WordPress block-based theme on your own.

What is a block theme?

A block theme is a WordPress theme whose template is made entirely of blocks. In addition to web pages and posts, one can create or modify different areas of the entire website such as header, footer, sidebar, etc using blocks.

A block theme is a WordPress theme with templates entirely composed of blocks so that in addition to the post content of the different post types (pages, posts, …), the block editor can also be used to edit all areas of the site: headers, footers, sidebars, etc.

Gutenberg Handbook

The structure of a simple block theme –

theme
|__ style.css
|__ theme.json
|__ functions.php
|__ templates
    |__ index.html
    |__ single.html
    |__ archive.html
    |__ ...
|__ parts
    |__ header.html
    |__ footer.html
    |__ sidebar.html
    |__ ...

For full site customization, check out the 10 best WordPress block themes. What is a block template?

What is a block template?

A list of WordPress blocks is needed to create a block template. Any WordPress block can be used to create a block template and content that was used to create parts of the template can be reused for creating other parts of the template. You just need to use “Template Parts” for this.

For instance, you can get the header.html from a separate template and include that header for all the WordPress block templates.

Here is a structure of a simple block template –

<!-- wp:site-title /-->
 
<!-- wp:image {"sizeSlug":"large"} -->
<figure class="wp-block-image size-large">
    <img src="https://cldup.com/0BNcqkoMdq.jpg" alt="" />
</figure>
<!-- /wp:image -->
 
<!-- wp:group -->
<div class="wp-block-group">
    <!-- wp:post-title /-->
    <!-- wp:post-content /-->
</div>
<!-- /wp:group -->
 
<!-- wp:group -->
<div class="wp-block-group">
    <!-- wp:heading -->
    <h2>Footer</h2>
    <!-- /wp:heading -->
</div>
<!-- /wp:group -->

Create WordPress Block Theme With These Essential Steps

Good! Now that you have learned WordPress block themes and block templates, then take a look at the process of creating a WordPress block theme.

Required files and structure

Two main files are required to create not only a block theme but also any theme, they are – index.php and style.css. To make WordPress plugins recognize that it is a block theme or the theme is active, an index.html template must also be included in the folder called templates.

Note – 

Before creating or using a block theme, make sure the Gutenberg plugin is activate
Setup theme

Now it’s time to set up the block theme. First, create a new folder with a proper name (we are going to use Themeim-tutorial in this article) inside –

/wp-content/themes/

Inside this folder, create the templates and parts folders.

After that, create a style.css file inside the root folder

/*
Theme Name: Themeim-tutorial
Author: Themeim
Description: A short description of the theme.
Version: The version, written in X.X or X.X.X format.
Requires at least: The oldest main WordPress version supported, written in X.X format. 
Tested up to: The last main WordPress version the theme has been tested up to, i.e. 5.9. Write only the number.
Requires PHP: The oldest PHP version supported, in X.X format, only the number.
License: The license of the theme.
License URI: The URL of the theme license.
Text Domain: The string used for textdomain for translation. The theme slug.
*/  

Note – 
The file header in the style.css must have the same items that you would use for a classic theme

Also, create a blank index.html file inside the templates folder. This will act as a fallback if the theme is activated without Gutenberg.

You can also create a function.php file as an option. This will allow you to enqueue style.css, include additional files, and enable an editor stylesheet.

<?php
if ( ! function_exists( 'fse_tutorial_theme_setup' ) ) :
    /**
     * Sets up theme defaults and registers support for various WordPress features.
     *
     * Note that this function is hooked into the after_setup_theme hook, which runs
     * before the init hook. The init hook is too late for some features, such as indicating
     * support for post thumbnails.
     */
    function fse_tutorial_theme_setup() {
        /**
         * Add default posts and comments RSS feed links to <head>.
         */
        add_theme_support( 'automatic-feed-links' );
 
        /**
         * Enable support for post thumbnails and featured images.
         */
        add_theme_support( 'post-thumbnails' );
 
        add_theme_support( 'editor-styles' );
 
        add_theme_support( 'wp-block-styles' );
    }
endif;
add_action( 'after_setup_theme', 'fse_tutorial_theme_setup' );
 
/**
 * Enqueue theme scripts and styles.
 */
function fse_tutorial_theme_scripts() {
    wp_enqueue_style( 'Themeim-tutorial-style', get_stylesheet_uri() );
}
add_action( 'wp_enqueue_scripts', 'fse_tutorial_theme_scripts' );
Create templates and template parts

There are many ways to create a template. Before going further with this step, make sure you have installed and activated your theme.

Let’s take a look at the ways of creating a template –

  • Create block templates manually by creating HTML files that contain block markup
  • Use template editing mode in the block editor 
  • Use the site editor tool to create a block template.

For in-depth instruction on creating a block template using any of these methods, you should definitely read here.

After that, you need to create block template parts. These parts are not essential, but they help the developers to keep the theme structure with reusable and smaller parts. Template parts are like blocks and they act as a container for other blocks. Usually, they are HTML files that should be placed inside the parts folder.

For example –

/parts/header.html is the correspondent of header.php

Great! Your theme should now include the following files and folders –

theme
 |__ style.css
 |__ functions.php (optional)
 |__ index.php
 |__ templates
    |__ index.html
 |__ parts
    |__ header.html
    |__ footer.html
Export templates and template parts

The templates and template parts that you have created earlier will be saved in the database as custom post types. Following these steps, you can export them as theme files –

  1. Inside the site editor, open – 
  2. More tools >> Options
  3. A zip file containing all the necessary files will be downloaded as soon as you select the Export option. 
  4. Once the zip is downloaded, unpack the files.
  5. Now copy the new index.html file from the theme/templates/ and paste it into the templates folder. 
  6. Then, copy the files (header.html and footer.html) from the parts folder and paste them inside your theme’s parts folder. 
  7. Open index.html and update the template part slugs in the block markup.

The saved templates have priority over theme files. To use the updated theme files –

  • Appearance > Templates
  • Appearance > Template parts
  • Then, delete the saved templates
Additional templates for blog, posts, and pages

Now the theme has a basic header and footer, it will not display any content. You will have to use a query loop and post template blocks to create a list of posts.

Open the index template and add a group of blocks that will work as a post container. Inside this group of blocks, enable the width options by using the “layout”:{“inherit”:true}

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
<!-- wp:group {"layout":{"inherit":true}} -->
<div class="wp-block-group"></div>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

The <div> in the group block should be changed to the <main> element. Use the tagName attribute to do this.

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
<!-- wp:group {"layout":{"inherit":true},"tagName":"main"} -->
<main class="wp-block-group"></main>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Okay! Now insert a query loop block inside the same group. When you will use a query loop block inside the editor, you will be allowed to use an empty loop.

Query look block example markup –

<!-- wp:query -->
<div class="wp-block-query"><!-- wp:post-template -->
<!-- wp:post-title /-->
<!-- wp:post-date /-->
<!-- wp:post-excerpt /-->
<!-- /wp:post-template --></div>
<!-- /wp:query -->

That being said, you can also add a query pagination block. Remember, it should be inside the query loop but outside the post template –

<!-- wp:query -->
<div class="wp-block-query"><!-- wp:post-template -->
<!-- wp:post-title /-->
<!-- wp:post-date /-->
<!-- wp:post-excerpt /-->
<!-- /wp:post-template -->
 
<!-- wp:query-pagination -->
<div class="wp-block-query-pagination">
<!-- wp:query-pagination-previous /-->
<!-- wp:query-pagination-numbers /-->
<!-- wp:query-pagination-next /--></div>
<!-- /wp:query-pagination -->
 
</div>
<!-- /wp:query -->

Next, we are going to create templates to display single posts. In case, you want to directly edit the theme files; then create a file called single.html inside the templates folder.

Then, add the site header and site footer template parts like below-

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
 
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Here, you have to create a group block again to have a post container like we did before

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
<!-- wp:group {"tagName":"main"} -->
<main class="wp-block-group"></main>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Add your preferred blocks inside the group block. Here are some samples of the new blocks –

  • Post content: <!– wp:post-content /–>
  • Post title: <!– wp:post-title /–>
  • Post author: <!– wp:post-author /–>
  • Post date: <!– wp:post-date /–>
  • Post featured image: <!– wp:post-featured-image /–>
  • Post tags: <!– wp:post-terms {“term”:”post_tag”} /–>
  • Post categories: <!– wp:post-terms {“term”:”category”} /–>
  • Next and previous post: <!– wp:post-navigation-link /–><!– wp:post-navigation-link {“type”:”previous”} /–>
Configure Global Styles with Theme.json

Before going any further, you should be clear about JSON format.

To enable or disable particular features, the theme.json file needs to be created. This is also needed when you want to set the default style for both your website and blocks. You can learn more about the global styles from here.

Start by creating a file called theme.json inside the main theme folder. Edit the file with two curly brackets –

{
 
}

Now, you have to be clear about the JSON version. There are particular JSON numbers for various Gutenberg versions. For instance, the JSON number 1 works for the Gutenberg 10.6 version.

{
    "version": 1,
}

Now, you have to create three main sections for Settings, Styles, and Template Parts where –

  • Settings – Here you can enable features and configure presets for styles
  • Styles – Here you can apply styles to elements, blocks, and even the website
  • Template Parts – Here you can assign template part files to designated areas

Don’t forget to separate each objects with commas like below –

{
    "version": 1,
    "settings": {
    },
    "styles": {
    },
    "templateParts": [
    ]
}

To enable or disable features, you can read the full process from here.

Ensure theme support for content width and full-width blocks

The layout setting will switch the add_theme_support( ‘align-wide’ ); line to enable width settings for template parts and group blocks. There is a benefit of enabling the layout settings in the theme.json file, which is you no longer need additional CSS to configure block width and alignment.

In order to achieve it, you need to work on 2 keys on the layout – contentSize and wideSize

Perhaps, taking a look at the example may give you an idea –

{
    "version": 1,
    "settings": {
        ...
        "layout": {
            "contentSize": "840px",
            "wideSize": "1100px"
        }
    }
}

Color Palette

You can either use the default palette for all blocks or a specific color palette to a single block. For this, you need to tweak the add_theme_support( ‘editor-color-palette’ ) line and use the following keys inside the palette –

  • Color – The hex color value 
  • Slug – The identifier for the color
  • Name – The visible name in the editor

Using the square brackets: [], multiple colors can be added as an array. Here is an example –

{
    "version": 1,
    "settings": {
        ...
        "color": {
            "palette": [
                {
                    "slug": "white",
                    "color": "#fff",
                    "name": "White"
                },
                {
                    "slug": "blue",
                    "color": "#0073AA",
                    "name": "WordPress blue"
                },
                {
                    "slug": "dark-grey",
                    "color": "#23282D",
                    "name": "Dark grey"
                }
            ]
        }
    }
}

To add a new color palette for the heading block, you need to start with a trailing comma after color. Use the following code for this –

"blocks": {
    "core/heading": {
        "color": {
            "palette": [
                {
                    "slug": "white",
                    "color": "#fff",
                    "name": "White"
                },
                {
                    "slug": "medium-blue",
                    "color": "#00A0D2",
                    "name": "Medium blue"
                }
            ]
        }
    }
}

Typography

If you like to add custom font sizes, you need to work on add_theme_support( ‘editor-font-sizes’ ). For this, create a new section called typography under the settings.

"typography": {
    "fontSizes": [
    ]
}

These keys are used by fontSizes

  • Slug – A unique identifier for the size
  • Size – A unit less size value
  • Name – A visible name in the editor
"typography": {
    "fontSizes": [
        {
            "slug": "normal",
            "size": "20px",
            "name": "normal"
        },
        {
            "slug": "extra-small",
            "size": "16px",
            "name": "Extra small"
        },
        {
            "slug": "large",
            "size": "24px",
            "name": "Large"
        }
    ]
}

To apply size to block, create a new section called blocks inside styles

"blocks": {
 
}

Just like the code below, name the blocks that you want to set as default –

"blocks": {
    "core/paragraph": {
    },
    "core/post-terms": {
    },
    "core/post-title": {
    }
}

Lastly, define the typography setting and fontSize value –

"blocks": {
    "core/paragraph": {
        "typography": {
            "fontSize": "var(--wp--preset--font-size--normal)"
        }
    },
    "core/post-terms": {
        "typography": {
            "fontSize": "var(--wp--preset--font-size--extra-small)"
        }
    },
    "core/post-title": {
        "typography": {
            "fontSize": "var(--wp--preset--font-size--large)"
        }
    }
}

Create block elements

Create block elements as many as you want. Just remember, some blocks have multiple elements. Some of these elements can be different depending on the settings. Since your theme will have custom padding enabled, you can also add padding to make the background more visible –

"styles": {
    "blocks": {
        "core/post-excerpt": {
            "elements": {
                "link": {
                    "color": {
                        "text": "var(--wp--preset--color--white)",
                        "background": "var(--wp--preset--color--blue)"
                    },
                    "spacing": {
                        "padding": {
                            "top": "1em",
                            "right": "1em",
                            "bottom": "1em",
                            "left": "1em"
                        }
                    }
                }
            }
        }
    }
}

Conclusion

Okay, we have come to the end of today’s discussion. If you have come this far, you should have built a WordPress block theme by now. If you get stuck at any point during the development process, you can always watch tutorials. You can also get expert’s help to overcome any problem.

We hope you have enjoyed reading this article. Feel free to leave a comment if you are confused about any part of this article.

Editor Team


We are a group of WordPress experts (editorial team) from Themeim. All of these articles go through manual testing to reveal the ultimate outcome.