What Is a WordPress Block Theme and How Does It Work

The WordPress theming paradigm has experienced its most profound shift since the release of the template hierarchy two decades ago. With the arrival of Full Site Editing (FSE), block themes have replaced rigid PHP templates with modular HTML files and structured JSON configurations. This architectural shift empowers content creators and developers to build, customize, and maintain websites using block-level modularity. This article breaks down what a WordPress block theme is, how its directory is structured, and how it executes under the hood.

The Core Anatomy of a WordPress Block Theme

In classic WordPress theming, a theme required a sprawling collection of PHP template files—such as header.php, footer.php, index.php, single.php, and sidebar.php—interleaved with WordPress template tags and custom PHP loops.

A block theme restructures the entire architecture into declarative HTML templates and structured data files. At its foundation, a modern block theme contains the following directory tree:

my-block-theme/
├── theme.json
├── style.css
├── functions.php          (optional)
├── templates/
│   ├── index.html
│   ├── single.html
│   ├── page.html
│   ├── archive.html
│   └── 404.html
├── parts/
│   ├── header.html
│   ├── footer.html
│   └── sidebar.html
└── patterns/
    ├── hero.php
    └── pricing.php

Notice the key difference: the presentation templates inside /templates and /parts are .html files rather than .php files. Inside these HTML files, you find Gutenberg block comments representing native WordPress blocks:

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
  <!-- wp:heading {"level":1} -->
  <h1>Welcome to Our Platform</h1>
  <!-- /wp:heading -->
  <!-- wp:paragraph -->
  <p>Building high-speed web apps has never been simpler.</p>
  <!-- /wp:paragraph -->
</div>
<!-- /wp:group -->

WordPress parses these HTML comment delimiters into structured DOM trees on the server before transmitting rendered markup to the browser.

How Block Themes Differ from Classic PHP Themes

To grasp why block themes represent an architectural breakthrough, examine how they handle four core operational challenges compared to classic themes:

1. Templating Language

Classic themes mix PHP logic with HTML markup. If an editor wanted to move a sidebar or add a callout box above an article, a developer had to modify PHP files and deploy code changes. Block themes use pure HTML block markup, which can be edited visually within the WordPress Site Editor without touching server-side source files.

2. Styling and Design Tokens

In classic themes, styling was governed by monolithic style.css sheets or dynamic CSS generated via PHP customizer hooks. Block themes replace this with theme.json, defining colors, typography, fluid font sizes, and layout dimensions in a unified JSON schema.

3. Asset Enqueuing and Performance

Classic themes typically enqueued large global stylesheets containing every CSS rule for every potential UI element on the site. Block themes leverage block-level CSS loading: WordPress scans the current page and only enqueues the specific stylesheet rules needed for blocks present in that render tree. This drastic reduction in unused CSS boosts Core Web Vitals scores.

The Role of theme.json: Centralizing Global Styles and Settings

The theme.json configuration file is the single most important component of a block theme. It performs three critical jobs simultaneously:

1. Defines Design Tokens: Generates CSS custom properties (variables) for colors, font families, font sizes, line heights, and spacing presets:

   {
     "settings": {
       "color": {
         "palette": [
           { "slug": "primary", "color": "#2563eb", "name": "Primary Blue" },
           { "slug": "surface", "color": "#f8fafc", "name": "Surface Light" }
         ]
       }
     }
   }
   

2. Controls Editor Capabilities: Toggles specific editor UI controls on or off for users, preventing accidental deviations from brand standards (e.g., disabling custom inline color pickers while permitting typography adjustments).
3. Applies Base Element Styling: Assigns styling rules directly to HTML tags (like <a>, <h1>, <blockquote>) and specific block types across the entire site without writing manual CSS.

Block Templates, Template Parts, and Patterns Explained

Three distinct abstractions work together inside a block theme to assemble full web pages:

1. Block Templates (/templates)

Templates govern the overall layout of specific URL routes in WordPress. For example, single.html defines how individual blog posts render, while archive.html handles tag and category listings. When a visitor requests a URL, the WordPress template hierarchy identifies the appropriate .html file inside the theme's /templates folder.

2. Template Parts (/parts)

Template parts are reusable layout fragments that repeat across multiple templates, such as headers, footers, announcement banners, and sidebars. When an editor updates a template part in the Site Editor, that change cascades globally to every template that references it.

3. Block Patterns (/patterns)

Patterns are pre-arranged arrangements of blocks designed for specific marketing or editorial purposes—such as customer testimonials, pricing comparison grids, FAQ accordions, and newsletter signups. Unlike template parts, inserting a pattern copies the block markup into the post content, allowing editors to modify text, images, and layouts independently without affecting other instances.

How WordPress Renders a Block Theme at Runtime

When an HTTP request reaches a WordPress site powered by a block theme, the server executes a streamlined rendering pipeline:

1. Route Resolution: WordPress analyzes the request URI and queries the database for matching content.
2. Template Selection: The template loader inspects the /templates directory for the most specific matching HTML template according to the standard template hierarchy.
3. Database Override Check: If an administrator has customized that template using the Site Editor, WordPress fetches the user-modified template stored in the database (wp_template custom post type) rather than reading from disk.
4. Block Parsing: The Gutenberg block parser evaluates HTML block comments (<!-- wp:... -->), resolving dynamic block attributes and server-rendered data (such as post title, content, or query loops).
5. Dynamic CSS Generation: WordPress generates an inline <style> block containing only the CSS rules and CSS variables required for the resolved blocks.
6. HTML Response: Clean, optimized HTML is returned to the client browser.

Classic Themes vs Block Themes Comparison

Modernize Your WordPress Infrastructure

Understanding the mechanics of block themes allows engineering teams and agencies to deliver faster websites with lower maintenance overhead and intuitive client editing experiences.

• Explore Nexora — Premium SaaS & Tech Startup WordPress Block Theme and modern WordPress templates for full-site editing.
• Compare the best WordPress block themes, learn how to create a WordPress block theme, or review block themes vs classic themes.
• Looking to build content-driven web apps? Review high-performance Astro templates and Next.js templates.
• Launching an editorial publication? Browse dedicated Blog templates with optimized readability.
• Need a full digital commerce or SaaS platform? Check out our Ecommerce templates, SaaS templates, and Starter Kits.

Or browse our complete marketplace of web framework templates to find the right foundation for your stack.