Template parts vs block patterns: when to use each in the Site Editor
How template parts and block patterns differ in WordPress block themes, where each is stored, and how to avoid template corruption on client handoffs.
A template part is a shared piece of a template, such as a header or footer, so one edit changes every template that uses it. An ordinary block pattern is a starting layout: inserting it copies its blocks into the page, and later edits stay on that page. Use a template part for what must match across the site, and a pattern for what each page owns.
When developing block themes and configuring the WordPress Site Editor, agencies and freelance developers frequently blur the architectural boundary between template parts and block patterns. Both mechanisms hold collections of core blocks, and both can be browsed and inserted directly from the editor inserter.
However, they operate in completely different layers of the WordPress database, template hierarchy, and publishing workflow. Confusing the two leads to template corruption, unexpected site-wide edits, and frustrating client handoffs where an innocent text change on an About page unintentionally alters every template across the site.
The architectural boundary: frame versus content#
The most reliable rule of thumb for block theme architecture is a clear separation of responsibility:
- Template parts define the global structural frame of your website (headers, footers, persistent sidebar widgets, mobile slide-out menus). They belong inside templates and apply site-wide.
- Block patterns define modular content sections (hero bands, pricing grids, testimonial groups, feature cards). They belong inside individual pages and posts.
| Property | Template parts | Block patterns (unsynced) | Synced patterns |
|---|---|---|---|
| Storage location | parts/*.html file or wp_template_part post | Inline in post post_content | wp_block post in database |
| Edit scope | Global: updates all referencing templates | Local: isolated to that specific page | Global: updates all referencing instances |
| Insertion target | Theme templates (index.html, single.html) | Post or page canvas via editor | Post or page canvas via editor |
| Client edit risk | High: accidental edits alter site frame | Low: safe for everyday content editing | Moderate: requires training to avoid global edits |
Here is an example of a sophisticated structural footer composition combining an interactive motion ribbon with a stationary colophon:
How template parts operate in the database#
A template part starts its life as an HTML file inside your theme's parts/ directory (for example, parts/header.html):
<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
<!-- wp:site-logo /-->
<!-- wp:navigation {"layout":{"type":"flex","justifyContent":"right"}} /-->
</div>
<!-- /wp:group -->
When you reference this part inside a template like templates/single.html, WordPress writes a reference block comment:
<!-- wp:template-part {"slug":"header","theme":"mytheme","tagName":"header"} /-->
When an administrator edits this header in the Site Editor, WordPress does not rewrite the physical parts/header.html file on disk. Instead, WordPress creates a new customized record in the wp_posts database table with the post type wp_template_part.
From that moment forward, WordPress prioritises the database record over the theme file. If you subsequently update parts/header.html in git and deploy to the server, your code changes will not appear on the live site until the user's database customizations are cleared in the Site Editor.
Why using template parts for page sections causes problems#
A common mistake in bespoke client builds is treating template parts as section components. Developers sometimes create files like parts/services-grid.html or parts/team-roster.html and drop them onto page templates.
This practice introduces three severe operational hazards:
- Unintended site-wide edits: If an editor modifies a team member's bio in the Site Editor under the impression that they are editing only the "About Us" page, that edit updates simultaneously on every other template referencing that part.
- Template pollution: Editorial content becomes trapped inside
wp_template_partdatabase rows rather than standardpost_content. Search plugins, automated translation tools, and XML/REST API exporters frequently fail to index text stored inside template part post types. - Loss of editorial agility: Content authors cannot reorder, duplicate, or delete sections on a per-page basis. The page layout remains locked to the rigid structure dictated by the template file.
Page-specific sections must always be inserted as block patterns directly into standard post_content.
How block patterns keep content agile and safe#
Block patterns provide pre-designed layouts without creating brittle global dependencies. When an author inserts a pattern into a page, the editor serialises the complete HTML markup directly into that post's post_content:
<!-- wp:group {"align":"full","layout":{"type":"constrained"}} -->
<div class="wp-block-group alignfull">
<!-- wp:heading {"level":2} -->
<h2 class="wp-block-heading">What we deliver</h2>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p>Editorial flexibility with standard core primitives.</p>
<!-- /wp:paragraph -->
</div>
<!-- /wp:group -->
The author can rewrite headlines, adjust paragraph text, replace photographs, and delete redundant columns freely on that page without any risk of breaking other templates or altering global site layouts.
Understanding synced patterns and instance overrides#
WordPress also offers synced patterns (formerly known as reusable blocks). A synced pattern stores its markup in a single wp_block post in the database. When inserted into a page, it writes a lightweight pointer block:
<!-- wp:block {"ref":420} /-->
Editing a synced pattern updates every page that references it. This makes synced patterns ideal for recurring calls to action, opening hours, or legal disclaimers.
With synced pattern overrides, developers can lock the visual layout of a synced pattern while allowing authors to override specific text or image attributes on a per-instance basis. The master pattern continues to control margins, padding, and colours, while individual pages display customized copy.
Client handoff rules for block themes#
To establish a smooth, reliable editing experience for non-technical clients:
- Limit template parts strictly to the structural frame: Use template parts exclusively for headers, footers, and persistent sidebars.
- Deliver page sections as block patterns: Supply heroes, feature grids, pricing tables, and case study layouts as unsynced patterns that drop directly into
post_content. - Lock structural wrappers: Apply block locking (
"lock":{"move":true,"remove":true}) to template parts in base templates so clients cannot accidentally delete site headers in the Site Editor. - Use content-only locking for sensitive sections: Where a section layout must remain rigid, apply
"templateLock":"contentOnly"to allow copy edits while preventing structural accidents.
Pattern Paste provides 542 curated WordPress block patterns designed to drop cleanly into post_content, keeping your theme templates lean and protected. Browse the catalogue, or read four ways to add a block pattern to WordPress.
From the library






