Block themes changed how WordPress developers think about site structure. Instead of PHP template files scattered across a theme directory, block themes use HTML files with block markup that the Site Editor can modify visually. Template parts are the building blocks of this system, reusable sections like headers, footers, and sidebars that you define once and include across multiple templates.
If you have worked with classic themes, template parts in block themes serve a similar purpose to get_header(), get_footer(), and get_template_part() calls, but they work entirely through HTML files and the Site Editor. Understanding how to build and register template parts properly is essential for creating maintainable, modular block theme architecture that scales well and gives site editors the flexibility they need.
This guide walks through creating template parts from scratch, registering them in theme.json, working with template part areas, understanding when to use template parts versus block patterns, nesting template parts for complex layouts, and exporting template parts for distribution.
What Template Parts Are and How They Work
A template part is an HTML file stored in your theme’s parts/ directory. Each file contains block markup that represents a reusable section of your site. When WordPress renders a page, it assembles the full template by combining the main template file with whatever template parts that template references.
The relationship between templates and template parts is straightforward. A template like templates/single.html might reference a header template part and a footer template part. The actual content of those parts lives in parts/header.html and parts/footer.html. The Site Editor can modify template parts independently, and changes propagate everywhere that part is used.
Here is a minimal example. Your templates/index.html file references template parts by their slug, which corresponds to the filename without the .html extension. The area attribute tells WordPress which type of template part this is, which affects how it appears in the Site Editor interface.
Creating Your First Template Parts
Template parts live in the parts/ directory of your block theme. The directory structure includes parts for header, footer, sidebar, and comments alongside your templates directory, theme.json, and style.css files.
Building a Header Template Part
A typical header template part includes the site title, navigation, and possibly a logo. A practical approach uses a constrained group layout with spacing that references theme.json presets, containing a flex group that positions the site title on the left and navigation on the right. The spacing values reference theme.json presets, which keeps the design consistent with your theme’s spacing scale.
Building a Footer Template Part
Footers typically contain copyright information, secondary navigation, and sometimes widget areas. A well-structured footer uses columns to organize content, one column for the site title and tagline, another for quick links using vertical navigation. Below the columns, a separator and centered copyright paragraph complete the layout.
Registering Template Parts in theme.json
Creating the HTML files is only half the work. You need to register your template parts in theme.json so WordPress knows about them and can display them properly in the Site Editor. Registration happens in the templateParts array, where each entry has three properties: name matching the filename without .html extension, title as the human-readable label shown in the Site Editor, and area determining which section this part belongs to.
Understanding Template Part Areas
WordPress defines three built-in template part areas that affect how parts are displayed and organized in the Site Editor:
- header, Parts that appear at the top of the page. The Site Editor groups these together and displays them with a header icon. When you add a template part block to a template, choosing the header area restricts the selection to header-area parts only.
- footer, Parts that appear at the bottom of the page. Same grouping logic as headers but for the footer section.
- uncategorized, The default area for parts that do not fit into header or footer categories. This includes sidebars, comment sections, content sections, and any custom reusable section you define.
You can also register custom template part areas using the default_wp_template_part_areas filter in PHP. Custom areas help organize template parts in the Site Editor when your theme has many parts that do not fit neatly into the three defaults.
Template Parts vs Block Patterns: When to Use Which
Block themes offer two mechanisms for reusable content: template parts and block patterns. They serve different purposes, and choosing correctly affects both the editing experience and maintenance overhead.
Template parts are structural elements that define site-wide sections. When you edit a template part, the change applies everywhere that part is used. They are managed through the Site Editor and are intended for structural elements that should be consistent across the site.
Block patterns are pre-designed block arrangements that users insert into content. Once inserted, the pattern becomes independent blocks with no connection to the original pattern definition. Editing the pattern definition does not update previously inserted instances. Patterns are best for content layouts, hero sections, pricing tables, team grids, call-to-action sections.
Key differences include: template parts stay synced across the site while patterns are independent after insertion. Template parts are managed via the Site Editor while patterns use the Block Inserter. Template parts live in the parts directory while patterns use the patterns directory or PHP registration. The introduction of synced patterns blurs the line slightly, but template parts remain the right choice for theme structure while synced patterns work best for editor-managed content.
Nesting Template Parts for Complex Layouts
Template parts can reference other template parts, which enables you to build complex layouts from simple, composable pieces. This is particularly useful for large sites where different sections of the header or footer need independent management.
Consider a site with a top bar for announcements, a main header with logo and primary navigation, and a mega menu. Instead of putting everything in one massive header.html, you can split it into nested parts: header.html references header-top-bar.html and header-main.html. Your footer.html can similarly reference footer-widgets.html and footer-bottom.html.
This approach gives site editors fine-grained control. They can modify the announcement bar without touching the main navigation, or update the footer widget layout without affecting the copyright section.
When Nesting Makes Sense
Nesting adds complexity, so use it strategically. Good candidates include headers with distinct sections, footers with widget areas separate from legal sections, sidebars with independent widget groups, and content sections that appear in some templates but not others. Avoid nesting more than two levels deep, deeply nested template parts become difficult to debug and can confuse site editors.
Creating Multiple Template Part Variations
Many themes ship with multiple header and footer variations. A minimal header for landing pages, a full header with mega navigation for the main site, a centered header for portfolio templates. Block themes handle this by creating separate template part files and registering each one in theme.json.
Templates can then reference whichever variation is appropriate. A landing page template might use the minimal header while the blog uses the full header. Site editors can also swap template parts in the Site Editor, when they select a template part block, the toolbar offers a Replace option that lists all registered parts in the same area. This means registering multiple variations gives editors the power to customize individual pages without writing code.
Styling Template Parts with theme.json
Template parts inherit global styles from theme.json, but you can also target them specifically using the styles section. When you set tagName to header in the template part block, WordPress wraps that part in a header element. You can target this through element-level or block-level styles in theme.json.
For more targeted styling, use CSS custom properties and utility classes within the template part markup itself. The block markup supports className attributes that you can use for targeted CSS, giving you precise control over individual template part styling.
Exporting Template Parts for Theme Distribution
When you build and customize template parts through the Site Editor, the modifications are stored in the database, not in your theme files. For theme distribution, you need to export these customizations back into the theme’s file structure.
Manual Export Process
The Site Editor includes an export feature. Navigate to the Site Editor, make your template part changes, then use the three-dot menu to select Export. This downloads a zip file containing all modified templates and template parts as HTML files. Extract the zip and copy the modified files into your theme’s parts directory.
Using the Create Block Theme Plugin
The Create Block Theme plugin is the recommended tool for theme developers. It provides options to save Site Editor modifications directly back to theme files, create child themes from customizations, export the entire theme as a zip, and reset database customizations to match theme files.
The workflow typically involves building initial template parts as HTML files, refining them visually in the Site Editor, using Create Block Theme to save changes back to files, committing updated files to version control, and resetting database customizations so theme files remain the source of truth.
Debugging Template Parts
When template parts do not render as expected, there are several common causes to investigate:
- File not found: The slug in the template part block must exactly match the filename in parts/. Check for typos and case sensitivity.
- Database override: If you edited the template part in the Site Editor, the database version takes precedence. Use the Site Editor’s Reset option to revert to the file-based version.
- Area mismatch: If a template part does not appear in the Site Editor’s selector, verify the area attribute matches between the block reference and theme.json registration.
- Block validation errors: Invalid block markup causes WordPress to fall back to the classic block. Check the browser console for validation errors.
Best Practices for Modular Block Theme Architecture
Building a well-architected block theme with template parts requires discipline around several key practices:
Keep template parts focused. Each part should have a single, clear responsibility. If your header has distinct sections, split them into nested parts rather than cramming everything into one file.
Use consistent naming conventions. Adopt a pattern like area-variant: header-minimal, header-centered, footer-large. This makes relationships immediately clear in both the file system and the Site Editor.
Leverage theme.json presets. Hardcoded pixel values create maintenance problems. Use theme.json presets for all spacing, font sizes, and colors so you change values once rather than editing every template part.
Document your template parts. Use descriptive titles in theme.json registration. “Header (Minimal, No Navigation)” is far more helpful than “Header 2.”
Test across templates. Template parts are shared, so changes affect every template using them. Verify rendering in all templates at different viewport sizes before shipping updates.
Plan for editor customization. Site editors will modify your template parts. Design them to be resilient, use layout blocks that maintain structure even when inner blocks are added, removed, or reordered.
Template parts in block themes represent a fundamental shift in how WordPress developers structure site layouts. The combination of file-based definitions, theme.json registration, visual editing through the Site Editor, and the composability of nesting gives you a system that is both developer-friendly and editor-friendly. Start with simple, focused parts, register them clearly, and expand as your theme’s requirements grow.