Reference

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.
PropertyTemplate partsBlock patterns (unsynced)Synced patterns
Storage locationparts/*.html file or wp_template_part postInline in post post_contentwp_block post in database
Edit scopeGlobal: updates all referencing templatesLocal: isolated to that specific pageGlobal: updates all referencing instances
Insertion targetTheme templates (index.html, single.html)Post or page canvas via editorPost or page canvas via editor
Client edit riskHigh: accidental edits alter site frameLow: safe for everyday content editingModerate: 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:

Live patternSignoff: Alternating motion banner above stationary footer
Open full ↗
Try dragging the comparison handle. Toggle between Designed (curated typography and palette) and Use my theme to see how the layout automatically adapts to theme tokens.

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:

  1. 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.
  2. Template pollution: Editorial content becomes trapped inside wp_template_part database rows rather than standard post_content. Search plugins, automated translation tools, and XML/REST API exporters frequently fail to index text stored inside template part post types.
  3. 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:

  1. Limit template parts strictly to the structural frame: Use template parts exclusively for headers, footers, and persistent sidebars.
  2. 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.
  3. 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.
  4. 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

The patterns in this post.

Keep reading.

All 16 articles

8 Themes · 542 patterns · 58 interactive

Your next site, finished sooner.

Start a whole site from a theme, or add one section to the site you have.

Browse themesSubscribe