WordPress Block Theme Development: A Complete Guide

WordPress block themes, introduced with WordPress 5.9, represent a fundamental shift from classic PHP-based themes to a block-based architecture. Instead of using template files with PHP template tags, block themes use HTML templates composed entirely of blocks. The site editor (a full-site editing experience) allows users to edit all parts of the site—headers, footers, sidebars, and content—using the same block editor interface used for posts and pages.

Theme Structure

A block theme requires only two essential files: style.css (for theme metadata) and theme.json (for global styles and settings). Template files are stored in the /templates/ directory as .html files composed of blocks using HTML comment markup. Template parts (reusable components like headers and footers) go in the /parts/ directory. The theme.json file is the heart of a block theme—it controls colors, typography, spacing, layout, and block-specific settings in a single configuration file.

my-block-theme/
├── style.css          # Theme header: Theme Name, Author, etc.
├── theme.json         # Global styles and settings
├── templates/
│   ├── index.html     # Main template
│   ├── single.html    # Single post view
│   ├── page.html      # Single page view
│   └── archive.html   # Archive/listing view
├── parts/
│   ├── header.html    # Site header
│   └── footer.html    # Site footer
└── assets/
    └── (optional CSS/JS files)

Using theme.json for Global Styles

The theme.json file defines the design system for your theme: color palette (text, background, link colors), font families and sizes, spacing scale, and block-specific presets. Settings define what options are available to users (e.g., which colors can be selected), while styles define the default appearance. This separation allows users to customize within defined constraints without breaking the design.

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        { "slug": "primary", "color": "#1a73e8", "name": "Primary" },
        { "slug": "secondary", "color": "#34a853", "name": "Secondary" },
        { "slug": "background", "color": "#ffffff", "name": "Background" },
        { "slug": "text", "color": "#202124", "name": "Text" }
      ]
    },
    "typography": {
      "fontFamilies": [
        { "slug": "inter", "fontFamily": "Inter, sans-serif", "name": "Inter" },
        { "slug": "merriweather", "fontFamily": "Merriweather, serif", "name": "Merriweather" }
      ]
    }
  },
  "styles": {
    "blocks": {
      "core/paragraph": { "typography": { "fontFamily": "var(--wp--preset--font-family--inter)" } },
      "core/heading": { "typography": { "fontFamily": "var(--wp--preset--font-family--merriweather)" } }
    }
  }
}

Creating Block Templates

Templates use block markup with HTML comments. For example, a simple single.html template includes the post title, featured image, content, and comments. The block markup uses WordPress’s block delimiter syntax: <!– wp:block-name {“attributes”} /–> for self-closing blocks and <!– wp:block-name –>…<!– /wp:block-name –> for blocks with content. Template parts are inserted with the wp:template-part block. Block themes eliminate the need for PHP template hierarchy, complex action hooks, and filter functions for most design concerns.

Block Patterns and Theme.json Variations

Block patterns are pre-designed layouts that users can insert from the block editor. They are registered in a /patterns/ directory and can include any combination of blocks with preset content, styles, and configurations. Patterns range from simple hero sections to full-page layouts. Theme.json style variations allow a single theme to offer multiple design presets (e.g., light, dark, high-contrast) that users switch between without changing the underlying content. Variations override specific theme.json properties like color palette, font sizes, and layout widths. Block themes represent the future of WordPress—Gutenberg’s phase 3 (collaboration) and phase 4 (multilingual) continue to extend the block editor’s capabilities, making block themes the recommended approach for all new WordPress projects.

Block Styles and Variations

WordPress 6.0+ introduced block style variations that let users switch between predefined visual styles for any block. A block style is registered in theme.json and appears as a style selector in the editor toolbar. Block variation registration creates new instances of existing blocks with preset attributes—for example, a Hero Section variation of the Cover block with predefined height and overlay color. The block.json metadata system defines block properties in a single JSON file, compatible with both PHP and JavaScript rendering. This makes block theme development accessible to developers who know JSON and CSS without needing deep PHP knowledge.

Block Theme Performance Advantages

Block themes load faster than classic themes because they generate minimal HTML. Classic themes often load enqueued CSS and JavaScript for every page, even when not needed. Block themes load only the assets required by the blocks present on each page. The style engine (WordPress 6.3+) generates inline CSS from theme.json settings, eliminating render-blocking external stylesheets. Global styles are cached and served as a single CSS file. Block themes also benefit from the Interactivity API (WordPress 6.5+) which enables client-side interactions without jQuery. Page build times are faster because block templates are parsed once and cached. For sites measuring Core Web Vitals, block themes consistently achieve better LCP (Largest Contentful Paint) and CLS (Cumulative Layout Shift) scores compared to equivalent classic themes.