How to Create a Block Theme in WordPress: Step-by-Step Guide

To create a block theme in WordPress, build a theme folder with a theme.json file for styles and a templates folder containing block-based template files like index.html. Use full site editing features by defining templates and template parts with HTML files using WordPress blocks.

Syntax

A WordPress block theme uses these key parts:

• theme.json: Defines global styles and settings.
• templates/: Folder with block-based HTML template files like index.html, single.html.
• template-parts/: Folder for reusable block parts like header and footer.
• style.css: Minimal file with theme info header.

Templates use HTML with WordPress block markup inside.

plaintext

/* style.css */
/*
Theme Name: My Block Theme
Author: Your Name
Version: 1.0
*/

/* theme.json */
{
  "version": 2,
  "settings": {},
  "styles": {}
}

<!-- templates/index.html -->
<!-- wp:group -->
<div class="wp-block-group">
  <!-- wp:post-title /-->
  <!-- wp:post-content /-->
</div>
<!-- /wp:group -->

Example

This example shows a minimal block theme structure with a simple homepage template using blocks.

plaintext

/* style.css */
/*
Theme Name: Simple Block Theme
Author: Dev Friend
Version: 1.0
*/

/* theme.json */
{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {"slug": "primary", "color": "#0073aa", "name": "Primary"}
      ]
    }
  },
  "styles": {
    "color": {
      "background": "#ffffff",
      "text": "#000000"
    }
  }
}

<!-- templates/index.html -->
<!-- wp:group {"align":"full"} -->
<div class="wp-block-group alignfull">
  <!-- wp:site-title /-->
  <!-- wp:paragraph -->
  <p>Welcome to my block theme homepage!</p>
  <!-- /wp:paragraph -->
</div>
<!-- /wp:group -->

Output

<div class="wp-block-group alignfull">
  <h1>Site Title</h1>
  <p>Welcome to my block theme homepage!</p>
</div>

Common Pitfalls

Common mistakes when creating block themes include:

• Missing or incorrect theme.json version or syntax causes styles to not apply.
• Not placing templates in the correct templates/ folder or using wrong file extensions.
• Forgetting the required style.css header with theme info.
• Using PHP template files instead of block-based HTML files for templates.

plaintext

/* Wrong style.css without header */
/* No theme info here */

/* Correct style.css header */
/*
Theme Name: Correct Block Theme
Author: Dev Friend
Version: 1.0
*/

Quick Reference

Summary tips for block theme creation:

• Use theme.json for global styles and settings.
• Put block templates as HTML files in templates/.
• Use template-parts/ for reusable blocks like header/footer.
• Include a minimal style.css with theme metadata.
• Test your theme in WordPress 5.9 or later for full site editing support.

Key Takeaways

Create a block theme by using a theme folder with theme.json and block-based HTML templates.

Always include a style.css file with theme metadata for WordPress to recognize the theme.

Use templates/ and template-parts/ folders to organize block templates and reusable parts.

Define global styles and settings in theme.json using version 2 format.

Test your block theme in WordPress 5.9 or newer to use full site editing features.