Know-how

WordPress Full Site Editing – A Complete Guide to FSE: theme.json, Templates, and Block Themes

Q: What is the theme.json file and what does it do in FSE?

theme.json is the central configuration file of a WordPress FSE block theme. It defines color palettes, typography, layout settings, editor controls, default block styles, and structural elements of the theme. WordPress generates CSS variables from it and configures the Site Editor interface.

Q: Can I use Full Site Editing with a classic WordPress theme?

Partially. Since WordPress 5.8, the theme.json file also works in classic themes – allowing configuration of colors, typography, and block editor settings. However, the full Site Editor (editing header, footer, templates) requires an FSE block theme.

Published: March 27, 2026 · Author: Marcin Szewczyk-Wilgan

WordPress Full Site Editing (FSE) is the most significant architectural change in WordPress history since the introduction of the Gutenberg editor in 2018. With Full Site Editing, the entire website – from the header, through page and post templates, to the footer – is built with blocks and managed visually from a single editor. No more scattered Customizer, PHP code in template files, or manually writing CSS for every layout change. WordPress FSE eliminates the need for third-party page builders in many scenarios and standardizes the way themes are built. In this article, we explain what WordPress Full Site Editing is, how it works technically, what the structure of a block theme looks like, what the theme.json file is, how to create templates and template parts in FSE, and when it is worth switching to Full Site Editing – and when it is better to stay with a classic theme.

What Is WordPress Full Site Editing?

WordPress Full Site Editing is a set of features introduced in WordPress 5.9 (January 2022) that extend the block editor (Gutenberg) to the entire site. Before FSE, blocks were used solely for building post and page content – the header, footer, sidebar, and templates remained under the control of PHP theme files. Full Site Editing changes this paradigm entirely.

In practice, WordPress Full Site Editing means that the header, footer, and navigation are built with blocks – just like page content. Templates defining the layout of pages, posts, archives, and 404 pages are HTML files containing blocks, not PHP files. Global Styles – colors, typography, margins, spacing – are configured centrally in the theme.json file and are visually accessible in the editor. Patterns (block patterns) are ready-made, reusable section layouts – hero sections, pricing tables, testimonials – that users insert with a single click.

FSE does not require the user to know code. At the same time, it gives developers full control over what users can change and what remains locked – through configuration in theme.json. You access the Full Site Editing editor via Appearance → Editor in the WordPress dashboard – provided the active theme is a block theme.

WordPress FSE vs. Classic Theme – Key Differences

A block theme compatible with Full Site Editing and a classic theme are two fundamentally different approaches to building a WordPress site. Understanding the differences is crucial before making a choice or migration decision.

Templates Classic theme: PHP files (single.php, page.php, archive.php) with WordPress functions like get_header(), the_content(). FSE block theme: HTML files in the /templates/ directory containing block markup.

Styling Classic theme: style.css file, often spanning thousands of lines, with style overrides in child themes. FSE theme: theme.json file defines color palettes, typography, spacing, and generates CSS variables automatically.

Customizer Classic theme: most appearance settings require the Customizer (Appearance → Customize). FSE theme: the Customizer is replaced by the Site Editor (Appearance → Editor), where everything is edited visually in Full Site Editing.

Widgets and sidebars Classic theme: register_sidebar() in functions.php, widgets added separately. FSE theme: widgets and sidebars do not exist as separate elements – their role is fulfilled by blocks inserted directly into templates and template parts.

Navigation Classic theme: wp_nav_menu() with PHP, registering menu locations in functions.php. FSE theme: Navigation block, configured visually in the Site Editor.

Block Theme Structure in WordPress Full Site Editing

A WordPress block theme compatible with Full Site Editing has a precisely defined directory structure. Here is the minimal yet complete structure of a production FSE theme:

my-fse-theme/ ├── parts/ │ ├── header.html │ └── footer.html ├── patterns/ │ └── hero-section.php ├── styles/ │ └── dark.json ├── templates/ │ ├── index.html │ ├── single.html │ ├── page.html │ ├── archive.html │ ├── 404.html │ └── search.html ├── functions.php ├── style.css ├── theme.json └── screenshot.png

/templates/ FSE page templates. Each file corresponds to a specific content type (post, page, archive, 404, search). In Full Site Editing, instead of PHP code – block markup in HTML.

/parts/ Template parts. Reusable structural elements in FSE: header, footer, sidebar. Referenced in templates via the template-part block.

/patterns/ Block patterns. PHP files with a header comment registering the pattern, containing block markup inside. Users insert them from the block inserter in the Full Site Editing editor.

/styles/ Style variations. Alternative JSON files defining a different set of colors and typography – users switch between them in the Site Editor with a single click.

theme.json The central configuration file of the FSE theme. Defines colors, fonts, editor settings, global and block-level styles.

style.css File required by WordPress for theme identification (Theme Name, Author, Version). In an FSE block theme, it may contain no CSS rules at all – styles are generated from theme.json.

functions.php Optional. You can still register fonts, enqueue additional styles, or extend functionality here – but in WordPress Full Site Editing, it is no longer the place for add_theme_support() for features controlled by theme.json.

The theme.json File – The Heart of a WordPress FSE Theme

The theme.json file is the central configuration element of every Full Site Editing theme. It replaces scattered add_theme_support() calls, CSS style overrides, and manual CSS variable creation. WordPress reads theme.json and uses it to generate CSS variables, configure the FSE editor interface, and define default block styles.

The current specification version is version 3 (from WordPress 6.6+). Here is an example of a complete theme.json with a color palette, typography, and layout configuration:

theme.json

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "appearanceTools": true,
    "color": {
      "palette": [
        { "slug": "primary", "color": "#d97b3a", "name": "Primary" },
        { "slug": "secondary", "color": "#3d3d3a", "name": "Secondary" },
        { "slug": "background", "color": "#faf9f5", "name": "Background" },
        { "slug": "surface", "color": "#ffffff", "name": "Surface" },
        { "slug": "muted", "color": "#6b5e4f", "name": "Muted" }
      ],
      "defaultPalette": false,
      "defaultGradients": false
    },
    "typography": {
      "fontFamilies": [
        {
          "fontFamily": "ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace",
          "slug": "mono",
          "name": "Monospace"
        },
        {
          "fontFamily": "'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
          "slug": "sans",
          "name": "Sans Serif"
        }
      ],
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" },
        { "slug": "medium", "size": "1rem", "name": "Medium" },
        { "slug": "large", "size": "1.25rem", "name": "Large" },
        { "slug": "x-large", "size": "1.75rem", "name": "Extra Large" },
        { "slug": "xx-large", "size": "2.5rem", "name": "2XL" }
      ],
      "fluid": true
    },
    "layout": {
      "contentSize": "720px",
      "wideSize": "1100px"
    },
    "spacing": {
      "units": ["rem", "px", "%"]
    }
  },
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--background)",
      "text": "var(--wp--preset--color--secondary)"
    },
    "typography": {
      "fontFamily": "var(--wp--preset--font-family--mono)",
      "fontSize": "var(--wp--preset--font-size--medium)",
      "lineHeight": "1.6"
    },
    "elements": {
      "link": {
        "color": { "text": "var(--wp--preset--color--primary)" }
      },
      "heading": {
        "typography": { "fontWeight": "700" }
      }
    },
    "blocks": {
      "core/button": {
        "color": {
          "background": "var(--wp--preset--color--primary)",
          "text": "var(--wp--preset--color--surface)"
        },
        "border": { "radius": "4px" }
      }
    }
  },
  "templateParts": [
    { "name": "header", "title": "Header", "area": "header" },
    { "name": "footer", "title": "Footer", "area": "footer" }
  ],
  "customTemplates": [
    { "name": "blank", "title": "Blank", "postTypes": ["page"] },
    { "name": "full-width", "title": "Full Width", "postTypes": ["page", "post"] }
  ]
}

What this file does in the context of WordPress Full Site Editing:

settings.color.palette Defines the color palette available in the FSE editor. WordPress generates CSS variables: --wp--preset--color--primary, --wp--preset--color--secondary, etc. Setting defaultPalette: false hides WordPress’s default colors.

settings.typography Registers font families and sizes available in Full Site Editing. Each becomes a CSS variable. The fluid: true flag enables fluid typography – sizes scale automatically between viewports.

settings.layout Defines contentSize (content width) and wideSize (width for “wide” blocks). Controls content centering and maximum width in the FSE editor.

settings.appearanceTools A single flag that enables margin, padding, border, line-height, and many other controls in the FSE editor.

styles Defines default styles for the entire site, individual HTML elements, and specific blocks. WordPress converts this configuration to CSS displayed both in the FSE editor and on the frontend.

templateParts / customTemplates Registers template parts (header, footer) and custom templates available in the Full Site Editing editor when creating pages and posts.

Templates and Template Parts in WordPress FSE

Templates in a Full Site Editing block theme are HTML files containing block markup – WordPress block tags in HTML comment format. Here is an example of a minimal templates/single.html template – a single post template in FSE:

templates/single.html

<!-- wp:template-part {"slug":"header","area":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">

  <!-- wp:post-title {"level":1} /-->
  <!-- wp:post-date {"format":"j F Y"} /-->
  <!-- wp:post-content {"layout":{"type":"constrained"}} /-->

  <!-- wp:spacer {"height":"2rem"} -->
  <div style="height:2rem" class="wp-block-spacer"></div>
  <!-- /wp:spacer -->

  <!-- wp:post-terms {"term":"category","prefix":"Categories: "} /-->
  <!-- wp:post-terms {"term":"post_tag","prefix":"Tags: "} /-->

</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","area":"footer"} /-->

And here is an example of a template part in FSE – the parts/header.html file:

parts/header.html

<!-- wp:group {"tagName":"header","style":{"spacing":{"padding":{"top":"1rem","bottom":"1rem"}}},"layout":{"type":"constrained"}} -->
<header class="wp-block-group" style="padding-top:1rem;padding-bottom:1rem;">

  <!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} -->
  <div class="wp-block-group">
    <!-- wp:site-title {"level":0} /-->
    <!-- wp:navigation {"layout":{"type":"flex","justifyContent":"right"}} /-->
  </div>
  <!-- /wp:group -->

</header>
<!-- /wp:group -->

Key dynamic blocks used in WordPress Full Site Editing templates:

wp:template-part Inserts a reusable template part (header, footer). The slug attribute points to a file in /parts/. This is the foundation of FSE’s modular architecture.

wp:post-title Dynamically renders the post or page title.

wp:post-content Renders the post/page content. Can have its own layout (constrained, flow).

wp:query The query loop block – equivalent of the classic while (have_posts()) loop. Allows displaying a list of posts with filters – one of the most powerful blocks in Full Site Editing.

wp:navigation The FSE navigation block. Replaces the classic wp_nav_menu() function.

wp:site-title / wp:site-logo Site name and logo pulled from WordPress settings – rendered dynamically in FSE templates.

Block Patterns in Full Site Editing

Block patterns are ready-made, predefined section layouts that users insert from the block inserter in the Full Site Editing editor. In the context of FSE, patterns are a powerful tool – they allow delivering ready-made hero sections, pricing tables, testimonials, and galleries without building them from scratch.

In an FSE block theme, patterns are registered as PHP files in the /patterns/ directory. WordPress automatically detects them and makes them available in the Full Site Editing editor. Here is an example of a hero section pattern:

patterns/hero-section.php

<?php
/**
 * Title: Hero Section
 * Slug: my-fse-theme/hero-section
 * Categories: featured
 * Keywords: hero, banner, header
 */
?>

<!-- wp:cover {"dimRatio":50,"overlayColor":"secondary","minHeight":500,
     "isDark":true,"layout":{"type":"constrained"}} -->
<div class="wp-block-cover is-dark" style="min-height:500px;">
  <span class="wp-block-cover__background has-secondary-background-color
    has-background-dim-50 has-background-dim"></span>
  <div class="wp-block-cover__inner-container">

    <!-- wp:heading {"textAlign":"center","level":1,
         "style":{"typography":{"fontSize":"2.5rem"}}} -->
    <h1 class="wp-block-heading has-text-align-center"
        style="font-size:2.5rem;">Your Hero Heading</h1>
    <!-- /wp:heading -->

    <!-- wp:paragraph {"align":"center"} -->
    <p class="has-text-align-center">A short description of your value proposition,
      service, or offer. Two sentences maximum.</p>
    <!-- /wp:paragraph -->

    <!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
    <div class="wp-block-buttons">
      <!-- wp:button -->
      <div class="wp-block-button"><a class="wp-block-button__link
        wp-element-button">Learn More</a></div>
      <!-- /wp:button -->
    </div>
    <!-- /wp:buttons -->

  </div>
</div>
<!-- /wp:cover -->

Since WordPress 6.3, synced patterns are available (previously called reusable blocks). A change in one place propagates to all instances of the pattern across the site. Unsynced patterns are copied on insertion and can be edited independently. In the context of WordPress FSE, synced patterns work perfectly for CTA headers, promotional banners, and elements reused across multiple templates.

Global Styles – Styling Your Site in WordPress FSE

Global Styles is the interface in the WordPress FSE Site Editor that allows users to visually change colors, typography, spacing, and block styles for the entire site – without touching code. Behind the scenes, Global Styles saves user changes as overrides of values from theme.json.

The style hierarchy in WordPress Full Site Editing:

1. Core defaults Default values built into WordPress core.

2. theme.json Values defined by the FSE theme developer.

3. Style variations Alternative sets of colors and typography defined in JSON files in the /styles/ directory.

4. User changes Overrides made by the user in the FSE Site Editor (Global Styles). These have the highest priority.

This hierarchy works analogously to the CSS cascade – each subsequent level overrides the previous one. The developer defines solid defaults in theme.json, and the user has the ability to customize them within the boundaries the developer set in the settings section. This is one of the key mechanisms of WordPress Full Site Editing – control without limiting flexibility.

Example: if you set settings.color.custom: false in theme.json, the user will not be able to pick a custom color outside the defined palette. If you set settings.typography.customFontSize: false – the user will only be able to choose from predefined font sizes. This gives the developer full control over visual consistency of the site in FSE.

Style Book – Previewing the Design System in FSE

WordPress (from version 6.2+) offers the Style Book tool, available in the Full Site Editing Site Editor. Style Book displays a preview of all blocks with currently applied styles – in a single view. Typography, colors, buttons, forms, headings, lists, quotes – all visible on one screen.

Style Book allows you to verify the consistency of the FSE theme’s design system before publishing. If you change the global font or color palette in Global Styles, Style Book immediately shows how the change affects every block in WordPress Full Site Editing. It is the equivalent of a “living style guide” known from front-end design systems – but natively built into WordPress.

For FSE theme developers, Style Book is an invaluable tool for verifying that theme.json generates a consistent design system – before the theme reaches the end user.

Custom Blocks in WordPress FSE – Building with Code

Full Site Editing is not limited to built-in blocks. Developers can create custom blocks that integrate with the FSE editor and use the theme.json styling system. Block registration in WordPress Full Site Editing is done via the block.json file:

block.json

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "my-theme/cta-box",
  "title": "CTA Box",
  "category": "design",
  "icon": "megaphone",
  "description": "A call-to-action block with heading, description, and button.",
  "supports": {
    "html": false,
    "color": {
      "background": true,
      "text": true
    },
    "spacing": {
      "padding": true,
      "margin": true
    },
    "typography": {
      "fontSize": true
    }
  },
  "textdomain": "my-theme",
  "editorScript": "file:./index.js",
  "style": "file:./style.css",
  "render": "file:./render.php"
}

The block.json file defines the block name, icon, category, and – most importantly – the supports section. It is the supports section that determines which controls from theme.json will be available for this block in the FSE editor: colors, spacing, typography. WordPress automatically generates appropriate CSS classes and variables for the block, maintaining consistency with the global Full Site Editing style system.

Custom blocks combined with theme.json and patterns create a complete design system where the developer controls the architecture, and the user controls content and visual personalization within WordPress FSE.

Migrating to WordPress Full Site Editing – Key Steps

Transitioning from a classic theme to a Full Site Editing block theme is not a trivial task, but it is fully achievable – even on a live production site. Here are the key stages of migrating to WordPress FSE:

Step 1

Audit the current theme

Identify all elements: which templates are in use, which widgets, which menu locations, which custom styles. Create a list of functions from functions.php that will need to be migrated or replaced in the new FSE theme.

Step 2

Backup and staging

Migration to Full Site Editing always takes place on a staging environment, never directly on production. A full backup of the database and files is the absolute minimum before starting work.

Step 3

Build theme.json

Transfer the color palette, typography, layout, and editor settings from style.css and functions.php to theme.json. This is the most challenging stage of FSE migration, requiring precise mapping of existing styles to JSON format.

Step 4

Convert templates to FSE

Transform PHP templates (header.php, footer.php, single.php) into HTML files with block markup in the /templates/ and /parts/ directories. Dynamic elements are replaced with corresponding Full Site Editing blocks.

Step 5

Patterns and widgets

Sections that were previously widgets or hardcoded in PHP become block patterns or template parts in the new FSE theme.

Step 6

Testing

Check all content types (pages, posts, archives, search, 404), responsiveness, performance, and plugin compatibility with Full Site Editing. Pay special attention to plugins that use the Customizer.

WordPress FSE Performance vs. Page Builders

One of the key advantages of WordPress Full Site Editing is performance. Classic page builders (Elementor, Divi, WPBakery) load their own CSS and JavaScript frameworks – often hundreds of kilobytes of additional code – regardless of which blocks the user actually uses. WordPress FSE works differently.

Block themes compatible with Full Site Editing use WordPress’s native rendering system. Styles are generated from theme.json as CSS variables, and only styles for blocks actually used on the page are loaded. WordPress automatically inserts inline styles for specific blocks, eliminating unused CSS. There is no additional JS framework on the frontend (except for interactive blocks using the Interactivity API).

Less CSS and JS FSE themes load only styles for blocks actually used on the page – no ballast of unused components typical of page builders.

Core Web Vitals Smaller resource size translates to better LCP, CLS, and INP scores – key performance metrics considered by Google.

Fewer HTTP requests No external frameworks means fewer files for the browser to download – faster first-view page loads.

No vendor lock-in Content built with WordPress blocks is portable between FSE block themes – changing themes does not require rebuilding content from scratch.

When to Choose Full Site Editing, and When a Classic Theme?

WordPress Full Site Editing is not a solution for every project. Here are practical guidelines for choosing between FSE and the classic approach:

FSE is a good choice when You are starting a new project from scratch and want maximum flexibility with minimal maintenance cost. You are building a site that should be easy for the client to edit without technical knowledge. Performance and Core Web Vitals compliance matter to you. You want to avoid vendor lock-in to a specific page builder.

A classic theme is better when You have an existing, complex site with deep page builder integration (Elementor Pro, Divi) and hundreds of pages – migrating to Full Site Editing would be too costly. Your critical plugins are not compatible with the FSE block editor. Your team is not ready for a workflow change and requires training.

Hybrid approach Since WordPress 5.8, you can use theme.json even in classic themes. You can gradually introduce Full Site Editing elements – e.g., color and typography configuration – without a full migration to an FSE block theme. This is a good transitional strategy.

Summary – The Future of WordPress Is Full Site Editing

WordPress Full Site Editing is not just another plugin or trend – it is a fundamental architectural change that defines the future of WordPress. The theme.json file replaces scattered configuration in PHP and CSS, HTML templates with block markup replace PHP templates, and the Site Editor gives users visual control over the entire site within FSE. Full Site Editing eliminates the need for page builders in many scenarios, improves performance, and standardizes how themes are built.

Switching to WordPress FSE requires an investment of time to learn the new architecture – but it pays off quickly: faster sites, easier maintenance, less code, and greater independence from third-party tools. With WordPress 7.0 and subsequent releases, Full Site Editing will only gain in functionality and maturity.

At WebOptimo, we build and maintain WordPress sites on both classic themes and Full Site Editing block themes. If you are considering migrating to FSE, need a block theme built from scratch, or want to consult whether WordPress Full Site Editing is right for your project – get in touch or check our WordPress development services.

Frequently Asked Questions About WordPress Full Site Editing

What is WordPress Full Site Editing (FSE)?+

WordPress Full Site Editing is a set of features that allow editing the entire website – header, footer, templates, navigation, and global styles – from the block editor. FSE replaces the Customizer and traditional PHP templates, giving users full visual control over the site without writing code.

Does Full Site Editing require a special WordPress theme?+

Yes. To use all WordPress FSE features, you need a block theme. Classic themes can use some FSE elements (e.g., theme.json), but full site editing requires a theme designed for FSE – such as Twenty Twenty-Four or Twenty Twenty-Five.

Will WordPress FSE replace page builders like Elementor or Divi?+

Full Site Editing offers a native, performant alternative to page builders. It does not require additional plugins, does not load external frameworks, and is built into WordPress core. For new projects, FSE is often a better choice in terms of performance and maintenance. Existing sites with deep page builder integrations may, however, stay with their current solution.

What is the theme.json file and what does it do in FSE?+

theme.json is the central configuration file of a WordPress FSE block theme. It defines color palettes, typography, layout settings, editor controls, default block styles, and structural elements of the theme. WordPress generates CSS variables from it and configures the Site Editor interface.

Can I use Full Site Editing with a classic WordPress theme?+

Partially. Since WordPress 5.8, the theme.json file also works in classic themes – allowing configuration of colors, typography, and block editor settings. However, the full Site Editor (editing header, footer, templates) requires an FSE block theme.

Is WordPress Full Site Editing safe and stable for a production site?+

Yes. FSE has been a stable part of WordPress core since version 5.9 (January 2022). With each subsequent release – 6.x and the upcoming 7.0 – Full Site Editing functionality is being expanded and stabilized. FSE block themes run on production sites worldwide.

How do I enable Full Site Editing in WordPress?+

Simply install and activate a block theme – e.g., Twenty Twenty-Five. After activating a block theme, the Appearance → Editor option will appear in the WordPress dashboard, giving access to the full site editor with the ability to edit templates, template parts, navigation, and global styles.

How does WordPress FSE differ from a page builder?+

Page builders (Elementor, Divi, WPBakery) are third-party plugins with their own CSS/JS frameworks that often bloat the site. WordPress Full Site Editing is a native WordPress core feature – it requires no additional plugins, generates less code, is faster, and provides full content portability between FSE block themes.