What is a WordPress block theme (Full Site Editing)?

A WordPress block theme is a theme built entirely on blocks. Every template (header, footer, single post, archive, 404, search) is stored as an HTML file in the /templates and /parts folders inside the theme. The whole site can be edited visually in the Site Editor at /wp-admin/site-editor.php without writing PHP. Block themes were introduced with WordPress 5.9 (January 2022) and require a theme.json file at the theme root that defines global styles (colors, typography, spacing, layout) in JSON. The first default block theme was Twenty Twenty Two (January 2022), followed by Twenty Twenty Three, Twenty Twenty Four (with patterns and the Editor refresh) and Twenty Twenty Five (January 2025). Full Site Editing (FSE) is the umbrella term for the editing experience that comes with block themes: Site Editor, global styles panel, template editing, template parts, navigation block, query loop block and the patterns directory at wordpress.org/patterns. Block themes coexist with classic themes (PHP based, using header.php, footer.php, functions.php and the Customizer). Both work in WordPress 6.x, but new theme development has moved to block themes since 2022 and the WordPress.org theme directory now flags classic themes as legacy.

What changed in WordPress 5.9 (January 2022)?

WordPress 5.9 shipped block themes and Full Site Editing as a stable feature after two years of work in the Gutenberg plugin (FSE was first previewed in Gutenberg 7.7 in March 2020). Key changes:

• The Site Editor replaces the Customizer for block themes. Customizer panels (header image, site identity, widgets, menus) are absent in block themes.
• Templates are HTML files with block markup (HTML comments like <!-- wp:paragraph -->), not PHP.
• The new theme.json file defines global styles. WordPress generates CSS variables from it at runtime.
• Widget areas are replaced by template parts and the Navigation block.
• The Query Loop block replaces custom WP_Query loops in templates for most use cases.

Block theme file structure

my-theme/
  style.css            (theme metadata header, can be almost empty)
  theme.json           (global styles, settings, palette, typography)
  functions.php        (optional, for enqueueing assets or hooks)
  templates/
    index.html
    single.html
    page.html
    archive.html
    404.html
    search.html
  parts/
    header.html
    footer.html
    sidebar.html
  patterns/
    hero.php           (registered patterns)
  assets/
    fonts/, images/, css/, js/

What does theme.json control?

theme.json is the central configuration file for a block theme. WordPress reads it at runtime and generates CSS custom properties plus block style presets. Common sections:

• settings.color.palette: the color palette shown in the editor and used for class names like has-primary-background-color.
• settings.typography.fontFamilies: font families with embedded font face declarations. Since WordPress 6.5 (April 2024) the Font Library can install fonts from Google Fonts locally.
• settings.spacing: spacing presets used by padding and margin controls and the spacing scale.
• settings.layout: contentSize and wideSize control the alignment options (default content width, wide alignment, full alignment).
• styles: default styles applied site wide and per block (e.g. styles.blocks.core/heading).
• customTemplates: register additional templates available in the page editor.
• templateParts: declare which parts (header, footer) are available and which areas they belong to.

Block theme vs classic theme

Hybrid themes and block template parts

Between classic and full block themes there are hybrid themes. A hybrid theme is a classic theme that opts into Full Site Editing features piece by piece. Examples:

• A classic theme can add theme.json to use global styles for blocks without converting templates.
• A classic theme can opt into block template parts by adding a parts/ folder and using block_template_part().
• A classic theme can add a templates/ folder with HTML templates for specific routes while keeping PHP templates for others.

Patterns and the pattern directory

Patterns are reusable block layouts. Since WordPress 6.0 (May 2022), themes can ship patterns as PHP files in the patterns/ folder with a header block. The wordpress.org/patterns directory has over 600 community patterns that any user can insert from the pattern picker. Synced patterns (formerly Reusable Blocks, renamed in WordPress 6.3 August 2023) store a single source instance that updates everywhere it is used.

Block themes and performance

Block themes are generally lighter than classic themes because they ship less CSS and let WordPress generate styles from theme.json. Key performance behaviors:

• WordPress only loads block stylesheets for blocks actually used on a page (since WordPress 5.8 August 2021, expanded in 6.1).
• theme.json generates one inline CSS block per page (typically 5 to 15 KB) instead of a separate stylesheet request.
• The Navigation block and Query Loop block run server side, so there is no extra JavaScript on the frontend by default.
• Twenty Twenty Four scores around 99 on PageSpeed Mobile with a base install, compared to 90 to 95 for Twenty Twenty One (classic).

Popular block themes in 2025

• Twenty Twenty Five: the default theme shipping with WordPress 6.7 (November 2024).
• Twenty Twenty Four: the all purpose theme from January 2024 with a large pattern library.
• Blocksy: free block theme with extensive patterns and a Pro extension.
• Kadence: hybrid theme with a strong block theme variant and global styles.
• Ollie: marketing focused block theme by Mike McAlister.
• Frost: minimal block theme by Brian Gardner.
• Spectra One, Inspiro: block themes with patterns aimed at agencies.

Migrating from a classic theme to a block theme

1. Audit the classic theme. List every Customizer setting, widget area and custom template part.
2. Choose a base block theme or scaffold a new one with npx @wordpress/create-block-theme (available since the Create Block Theme plugin, 2022).
3. Move the design system into theme.json: palette, typography, spacing.
4. Recreate templates in templates/ as HTML with block markup. Use the Site Editor to compose visually, then export.
5. Recreate header and footer as template parts in parts/.
6. Convert PHP based dynamic content (custom loops) to the Query Loop block or to dynamic blocks registered with register_block_type().
7. Test in staging. Many classic plugins assume Customizer or sidebar APIs and need configuration adjustments.

What InspectWP checks

InspectWP detects which theme is active, including block themes, the parent and child theme, and whether the theme has known security issues. The report flags outdated themes, missing theme support and signals like missing theme.json that suggest a classic theme on WordPress 6.x where a block theme upgrade may be considered.