Template Parts in WordPress Block Themes: A Developer Deep-Dive

By /

Template parts are the building blocks of every WordPress block theme’s structure. They define reusable sections like headers, footers, sidebars, and any other chunk of layout that appears across multiple templates. If you are building block themes, understanding template parts at a deep level is essential for creating maintainable, performant themes.

This guide covers the full template parts system: how they work under the hood, registration methods, the relationship with theme.json, advanced patterns, and practical techniques for building production-ready block themes.

How Template Parts Work in Block Themes

In classic WordPress themes, headers and footers lived in header.php and footer.php. Block themes replace this with HTML files containing block markup, stored in the parts/ directory.

A template part is an HTML file that contains Gutenberg block markup. WordPress loads these files and renders them wherever the template-part block reference appears in a template. The core block editor lets users modify template parts visually without touching code.

File Structure

your-theme/
├── parts/
│   ├── header.html
│   ├── footer.html
│   ├── sidebar.html
│   └── comments.html
├── templates/
│   ├── index.html
│   ├── single.html
│   ├── page.html
│   └── archive.html
├── theme.json
└── style.css

Every HTML file in parts/ is a template part. The filename (without extension) becomes the slug that identifies the part.

Registering Template Parts in theme.json

While WordPress auto-discovers HTML files in the parts/ directory, registering them in theme.json gives you control over their display names and designated areas.

{
  "version": 3,
  "templateParts": [
    {
      "name": "header",
      "title": "Header",
      "area": "header"
    },
    {
      "name": "footer",
      "title": "Footer",
      "area": "footer"
    },
    {
      "name": "sidebar",
      "title": "Sidebar",
      "area": "uncategorized"
    },
    {
      "name": "comments",
      "title": "Comments Section",
      "area": "uncategorized"
    }
  ]
}

The Three Standard Areas

WordPress defines three template part areas:

  • header: Displayed at the top of the Site Editor’s template structure. WordPress recognizes this area and applies header-specific behavior.
  • footer: Displayed at the bottom. Same structural recognition as header.
  • uncategorized: The default for any template part that is not a header or footer. Sidebars, comment sections, CTAs, and custom sections all go here.

The area assignment affects how template parts appear in the Site Editor’s template structure view. It does not change rendering behavior on the frontend.

Writing Template Part HTML

Template parts use standard Gutenberg block markup. Here is a practical header example:

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

And a footer with columns:

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
  <!-- wp:columns -->
  <div class="wp-block-columns">
    <!-- wp:column -->
    <div class="wp-block-column">
      <!-- wp:heading {"level":3} -->
      <h3>About</h3>
      <!-- /wp:heading -->
      <!-- wp:paragraph -->
      <p>Your site description here.</p>
      <!-- /wp:paragraph -->
    </div>
    <!-- /wp:column -->
  </div>
  <!-- /wp:columns -->
</div>
<!-- /wp:group -->

Using Template Parts in Templates

Reference a template part in any template file using the template-part block:

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

<!-- wp:group {"tagName":"main"} -->
<main class="wp-block-group">
  <!-- wp:post-content /-->
</main>
<!-- /wp:group -->

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

Key attributes:

  • slug: Matches the filename in parts/ (without .html extension).
  • area: Tells the Site Editor which structural area this part belongs to.
  • tagName: The HTML element wrapping the template part output. Use header, footer, aside, or div for semantic HTML.
Code displayed on laptop screen showing the structure of WordPress block theme template parts
Template parts replace the classic header.php and footer.php approach with structured HTML block markup files.

Template parts are the structural backbone of block themes. Get them right, and your theme becomes easy to maintain, extend, and customize. Get them wrong, and every template change becomes a headache.

Template Part Variations

Block themes can ship multiple versions of the same template part area. For example, you might offer three header styles: minimal, centered, and full-width with search.

parts/
├── header.html           (default)
├── header-centered.html  (variation)
├── header-minimal.html   (variation)
├── footer.html           (default)
└── footer-minimal.html   (variation)

Register all variations in theme.json:

{
  "templateParts": [
    { "name": "header", "title": "Header", "area": "header" },
    { "name": "header-centered", "title": "Header (Centered)", "area": "header" },
    { "name": "header-minimal", "title": "Header (Minimal)", "area": "header" },
    { "name": "footer", "title": "Footer", "area": "footer" },
    { "name": "footer-minimal", "title": "Footer (Minimal)", "area": "footer" }
  ]
}

Users can swap between header and footer variations directly in the Site Editor by selecting the template part block and choosing “Replace” from the toolbar.

Template Part vs Block Pattern: When to Use Which

This is one of the most common sources of confusion in block theme development. Both template parts and block patterns provide reusable content, but they serve different purposes.

Feature Template Part Block Pattern
Purpose Structural layout sections (header, footer) Content design patterns (hero, CTA, testimonial)
Reuse model Referenced (changes propagate to all templates) Copied (each instance is independent after insertion)
Location parts/ directory patterns/ directory
Editable in Site Editor Yes, with global propagation Yes, but only the inserted instance
Appears in template structure Yes (header/footer areas) No
Best for Elements that must stay consistent site-wide Starting points for content layouts

Use template parts for anything that should update globally when edited. Use patterns for content layouts that users customize per page. If you are building a header with a specific navigation structure, that is a template part. If you are providing a hero section layout, that is a pattern.

For a complete guide on patterns, read our article on creating custom block patterns in WordPress.

Styling Template Parts

Template parts inherit styles from your theme.json global styles configuration. You can also target template parts specifically in your theme’s CSS.

Using theme.json for Template Part Styles

Apply styles to the blocks inside template parts through the styles.blocks section of theme.json. Since template parts are composed of standard blocks, every block inside them responds to theme.json styling.

CSS Targeting

WordPress wraps each template part in a container element. You can target specific template parts using the tag name and class:

/* Target the header template part */
header.wp-block-template-part {
  position: sticky;
  top: 0;
  z-index: 100;
  background: var(--wp--preset--color--base);
}

/* Target the footer template part */
footer.wp-block-template-part {
  border-top: 1px solid var(--wp--preset--color--contrast);
  margin-top: var(--wp--preset--spacing--80);
}

Advanced Techniques

Conditional Template Parts

Different templates can use different template parts. A single-post template might use a minimal header, while the homepage uses a full-width header with hero section. Simply reference different template part slugs in each template file.

For example, templates/front-page.html can reference header while templates/single.html references header-minimal.

Nesting Template Parts

Template parts can include other template parts. Use this sparingly, but it is useful for complex layouts where a section like a top bar appears in multiple headers. Your main header part can reference a top-bar template part inside it.

Template Parts in Child Themes

Child themes can override parent theme template parts by placing a file with the same name in their own parts/ directory. WordPress checks the child theme first, then falls back to the parent theme. This follows the same override pattern as classic themes.

Common Mistakes and How to Avoid Them

  • Forgetting theme.json registration: Template parts work without registration, but they will not show proper names or area assignments in the Site Editor. Always register them.
  • Using wrong tagName: The tagName attribute should match the semantic HTML element. Use header for headers, footer for footers, and aside for sidebars. Default is div.
  • Over-nesting groups: Every wrapping group block adds a div to the output. Keep your template part markup as flat as possible for cleaner HTML and fewer layout issues.
  • Not testing user edits: Template parts are editable in the Site Editor. Test what happens when users modify, replace, or reset your template parts. Make sure your CSS does not break with different content.
  • Confusing template parts with synced patterns: Both provide global reuse, but template parts are structural and tied to theme templates. Synced patterns are content-level and reusable anywhere.

Frequently Asked Questions

What is the difference between a template and a template part?

A template defines the full page layout for a specific content type (single post, archive, 404). A template part is a reusable section within a template (header, footer, sidebar). Templates reference template parts using the template-part block.

Can users override theme template parts?

Yes. Users can edit template parts in the Site Editor, and their customizations are stored in the database. The original theme files remain unchanged. Users can reset to the theme default at any time.

How many template parts should a theme have?

Start with header and footer. Add more only when you have sections that genuinely need to be reused across multiple templates and edited globally. Three to six template parts is typical for a well-structured theme.

Do template parts affect performance?

Template parts add minimal overhead. WordPress loads them as part of the template rendering process. The performance impact comes from the blocks inside the template parts, not the template part system itself.

Can I use PHP in template parts?

No. Block theme template parts are pure HTML with block markup comments. If you need dynamic PHP logic, use a dynamic block or the render_block filter. The block markup approach is intentional since it enables visual editing in the Site Editor.

Scroll to Top