WordPress Block Themes: How They Work and When to Use One

A WordPress block theme is a theme built entirely from blocks: HTML template files instead of PHP, a single theme.json file for the design system, and block patterns for reusable sections. The practical marker is Full Site Editing (FSE), the ability to edit headers, footers, and page templates directly in the block editor under Appearance to Editor, rather than in code. This is not a fringe approach. Every default WordPress theme since Twenty Twenty-Two (released January 2022) is a block theme, and core development is now block-first, meaning new features like the Interactivity API, block bindings, and pattern overrides arrive as block-native capabilities. A classic theme still works, but it sits outside the direction WordPress is moving.

This guide explains the three structural differences from classic themes, where block themes win on Core Web Vitals, how theme.json and patterns fit together, and the cases where a classic theme is still the right call.

Block Theme vs Classic Theme: The Differences That Matter

A block theme differs from a classic theme on four practical axes: who can edit layouts, how design rules are stored, how much CSS and JS the page loads, and how portable the output is. Here is the comparison that decides most real projects.

The single biggest day-to-day change is editor independence. In a block theme, a content editor rearranges sections, swaps patterns, and edits the footer without touching code or a developer. In a classic theme, the same edits route through a developer or a page builder plugin. The WordPress block themes documentation is the authoritative reference, and the active debate in the r/WordPress community is less "are block themes good" and more "is the editing experience mature enough yet for complex sites," which is the honest tension this guide addresses head-on below.

What "Block-First" Actually Means in Practice

A block-first theme is one where every layout element is a native WordPress block, with no shortcodes and no proprietary page-builder components. Three things define it concretely.

Templates are block markup, not PHP. Your homepage template is an HTML file (templates/front-page.html) composed of block comments like <!-- wp:group --> and <!-- wp:cover -->, which the editor reads and modifies directly. There is no PHP logic mixed into presentation. Design tokens live in theme.json. Colors, font sizes, spacing, and layout widths are defined once in that file, which simultaneously controls the editor's available options and the front-end output. Patterns replace widgets and one-off sections. Reusable designs (a hero, a testimonial grid, a CTA) register as block patterns that editors insert with one click, inheriting their styling from theme.json.

The portability payoff is real and citable: block themes output clean, semantic HTML with no plugin lock-in. A Group block renders as a <div> or <section>, a Navigation block as <nav>, a Heading block as the correct <h1> through <h6>. Move hosts, switch tools, or hand the site to another team and the content stays intact. The Block Library Export feature produces exactly this portable block markup, and the SEO-ready theme architecture guide explains why this semantic markup quality directly supports rankings.

Where Block Themes Beat Classic Themes on Performance

Block themes outperform classic themes on Core Web Vitals for three structural reasons, not because of any single optimization. The gains are architectural, which is why they hold up across pages rather than requiring per-page tuning.

Per-block CSS loading. Block themes ship the CSS for a block only when that block is on the page. A page with no slider loads no slider styles. Classic themes with page builders commonly load 200 to 500KB of CSS on every page regardless of what the page uses; well-built block themes typically load a fraction of that. No jQuery by default. Block themes run on vanilla JavaScript. Classic themes and many builders still load jQuery (roughly 90KB) plus their own scripts on top, which directly inflates Interaction to Next Paint (INP). Server-rendered, lazy-loaded images. Block content renders as static HTML server-side, and WordPress applies native lazy loading with explicit width and height attributes that prevent Cumulative Layout Shift. Classic themes often need plugins to match this.

Web.dev's Core Web Vitals guidance confirms these patterns (smaller payloads, fewer render-blocking resources, dimensioned images) directly improve the LCP, INP, and CLS scores Google uses. For sites chasing competitive local keywords where Core Web Vitals can tip ranking positions, the architectural edge matters. The SaaS template demonstrates a block-first approach producing fast pages without giving up design flexibility.

How to Structure theme.json for a Real Design System

The theme.json file is the control center of a block theme, and structuring it well is what separates a coherent site from an "assembled" one. Four sections carry most of the weight.

Color palette. Define brand colors as a named palette: primary, secondary, accent, and neutrals, plus semantic colors for success, warning, and error states. Keep it under about a dozen total to avoid editor decision fatigue. Set "custom": false under color settings to remove the full RGB picker, so editors can only choose on-brand values. Typography scale. Define named sizes (small through xx-large) and map them to headings so H1 always uses the largest step. This keeps hierarchy consistent without editors hand-setting font sizes. Spacing presets. Define a scale (commonly 8, 16, 24, 32, 48, 64px) and use those values everywhere. Consistent spacing is the single biggest factor in whether a site looks designed rather than thrown together. Layout widths. Set a content width (around 720 to 800px for readability) and a wide width (around 1200 to 1400px for full-bleed sections) to constrain layouts sensibly.

Every value here becomes both a CSS custom property (--wp--preset--color--primary) and an editor option at once. The AI Site Brief generates a theme.json configuration from brand inputs (palette from a logo, type and spacing fit to content density), giving you a complete starting design system without manual configuration. For the deeper token architecture behind a durable system, the brand style DNA guide covers the three-tier global-semantic-component token model.

Block Patterns: The Reusable Sections That Build Pages

Block patterns are the most useful feature of block-theme development. A pattern is a pre-designed arrangement of blocks an editor inserts in one click, functioning as a section template: a hero, a service grid, a testimonial strip, a CTA.

Effective patterns are built by thinking in sections, not pages. Each should own one purpose: a hero pattern (background, H1, supporting text, CTA button), a service grid (icon, heading, description, link per card), a proof strip (testimonial plus project detail), an FAQ accordion (collapsible Q&A with FAQPage schema), a CTA section (heading, support text, button, background). Three rules keep patterns durable. Register them in the theme, in a patterns/ directory or functions.php, so they travel with the theme rather than a plugin. Make them content-aware, using inner blocks with placeholder content the editor replaces, never locked content that needs code changes. Document the library on a hidden noindex page that shows every pattern with its name, purpose, and usage notes, so the team builds pages consistently.

Templates then compose patterns into page-level structure. A front-page.html template stacks hero, trust strip, service grid, proof, and CTA patterns in a defined order, while each section's content stays editable. A single-service.html template arranges a service hero, description blocks, proof, FAQ, and CTA. The principle: templates define the skeleton, patterns define the sections, theme.json defines the design rules, and editors fill the specifics. When patterns reference theme.json tokens rather than hard-coded styles, updating one pattern changes it everywhere it appears. Pairing patterns with Brand Voice Training keeps both visual and tonal consistency intact.

Migrating an Existing Classic Theme to Block-First

Moving a classic-theme or page-builder site to a block theme works best as a phased migration that protects rankings, not a big-bang rebuild.

Phase 1: Build your theme.json. Encode your existing design system (colors, fonts, spacing) in theme.json. This does not change the current site; it prepares the design layer. Phase 2: Convert sections to patterns. Rebuild your highest-traffic page layouts as block patterns. A hero built in Elementor becomes a pattern of Cover, Heading, Paragraph, and Button blocks. Phase 3: Build templates from patterns. Start with your most common template (usually a service page), assemble it from new patterns, and test it against the original for visual fidelity and conversion. Phase 4: Migrate page by page. Move highest-traffic pages first, verify rankings hold for two to three weeks, then migrate the next batch, keeping the old theme deployable as a fallback. Phase 5: Retire the classic theme. Once all content is on block templates and rankings are stable, deactivate the old theme and remove builder plugins.

The conversion layout patterns guide covers which section designs to convert first for the biggest behavioral impact, and the theme refresh strategy guide covers the refresh-versus-rebuild decision in detail. For generating block themes from a brief rather than building by hand, the AI WordPress theme builder playbook walks through the AI-assisted path, and the consultant use case shows the workflow applied to professional services.

FAQ about wordpress block themes

Do I need to know PHP to build a WordPress block theme?

No. Block themes use HTML template files and theme.json for configuration, so you need HTML structure and basic CSS but not PHP for the theme itself. Pattern registration uses a small, repeatable amount of PHP (or a JSON-based pattern file), but it follows a documented format. This is one of the main reasons block themes lower the barrier to theme creation compared with classic PHP themes.

What is the difference between a block theme and Full Site Editing?

Full Site Editing (FSE) is the broader WordPress feature that lets you edit headers, footers, and templates in the block editor, not just post content. A block theme is the theme type that enables FSE. Every block theme is an FSE theme. "Block-first" specifically means designing your whole content strategy around block patterns, theme.json tokens, and portable block markup, rather than just having FSE available.

Can I use a page builder with a block theme?

Technically yes, but it undercuts the point. Page builders add their own CSS, JavaScript, and rendering layer on top of the block system, which negates the performance and portability advantages that make block themes worthwhile. If you are committed to a block theme, use the native block editor and block patterns. If you need a builder, you may be better off staying on a classic theme.

Are block themes ready for complex commercial sites in 2026?

For most marketing sites, service businesses, and content sites, yes. Core blocks plus custom patterns handle hero sections, service grids, testimonials, FAQs, and CTAs comfortably. The honest caveat the WordPress community raises: highly bespoke interactive layouts can still be faster to build in a mature page builder, and the FSE editing UX, while much improved, has more edge cases than a classic theme plus a builder you already know. Evaluate against your actual layout complexity, not the general trend.

Ready to build a block theme without writing template files by hand? Join wp0 early access and generate a complete block theme from a business brief.