Synced patterns are one of the most underused features in the WordPress block editor. Every block theme developer knows how to create patterns, define a block layout once, insert it anywhere. But most patterns are unsynced: once inserted, each instance is an independent copy. Change the original pattern definition and existing instances are unaffected. For one-off layouts, that is exactly right. For site-wide content, promotional banners, announcement bars, persistent CTAs, you need something different.
Synced patterns (formerly called Reusable Blocks) solve this. One definition, stored in the database as a wp_block post, rendered live across every instance. Update the synced pattern once and the change propagates everywhere it appears. This guide covers the full picture: how synced patterns work technically, how to register them both via PHP and the patterns/ directory, how to manage them in the Site Editor, the difference between fully synced and partially synced patterns, and the real-world use cases where they belong. For context on the broader pattern system, the previous article in this series covers block pattern categories in WordPress.
How Synced Patterns Work Technically
Under the hood, every synced pattern is a wp_block custom post type entry in the WordPress database. When an editor inserts a synced pattern into a page, WordPress does not copy the block markup into the page’s post content. Instead, it inserts a reference block:
<!-- wp:block {"ref":42} /-->The number 42 is the post ID of the wp_block entry. When WordPress renders this page, it fetches the wp_block post content and renders it inline. Every page, post, or template that contains a wp:block reference to the same ID renders the same content from the same source. Update the wp_block post and the change is live everywhere instantly, no need to find and update individual page instances.
This is fundamentally different from unsynced patterns. An unsynced pattern inserts its block markup directly into post content as a flat copy. The original pattern definition is just a template; once inserted, the instance has no relationship to the source pattern.
Synced vs. Unsynced: Choosing the Right Type
The decision between synced and unsynced comes down to one question: does every instance need to show the same content, or does each instance need to be independently editable?
Use synced patterns when:
- Content needs to be consistent across all instances (promotional banners, notification bars, legal disclaimers).
- You want one edit to propagate across the entire site without hunting down individual pages.
- The pattern represents brand-level content (contact info, certifications, awards) that should never diverge.
- You are building template parts that are not covered by the standard header/footer template part system.
Use unsynced patterns when:
- Each page needs its own version of the layout (hero sections, testimonial blocks per product).
- Editors need to customize the inserted pattern without affecting other pages.
- The pattern is a starting point or scaffold, not a persistent content component.
- The pattern contains page-specific content like a custom CTA tied to a specific product.
A useful mental model: synced patterns behave like template parts but at the content level rather than the structural level. Template parts manage global structure (the header wrapper, the footer layout). Synced patterns manage global content within that structure (the banner inside the header, the disclaimer in the footer).
Registering Synced Patterns via PHP
The register_block_pattern() function accepts a sync_status argument introduced in WordPress 6.3. Setting this to 'fully' makes the pattern synced. Omitting it or setting it to 'unsynced' gives you the default unsynced behavior.
When WordPress registers a PHP-defined synced pattern with sync_status: 'fully', it creates a wp_block post in the database the first time the pattern is encountered. Subsequent requests reuse the existing wp_block post. This means the PHP definition acts as a seed, it creates the initial database entry, but once an editor modifies the synced pattern through the editor UI, the database version takes precedence over the PHP definition.
This seeding behavior is important to understand when deploying themes across multiple sites. The PHP-registered pattern creates the initial database entry on first load, giving editors a pre-filled starting point. Editors can then customize it per-site without touching code.
Registering Synced Patterns via the /patterns/ Directory
Block themes can also register synced patterns using the patterns/ directory with a file header. The Synced: true header flag enables sync behavior for that pattern file.
The file-based approach integrates naturally with the theme’s directory structure and version control. Each synced pattern has its own file, making diffs and reviews straightforward. The pattern markup lives in the file; the database entry is created and maintained at runtime.
One caveat: once a synced pattern is registered and the database entry is created, modifying the PHP file or pattern directory file does not automatically update the database entry. The database version is authoritative after initial creation. To push a PHP update to an existing synced pattern, you would need to update the wp_block post directly or delete it and let it regenerate from the updated PHP definition on next load.
Managing Synced Patterns in the Site Editor
The Site Editor’s Patterns section (Appearance → Editor → Patterns) is the primary interface for managing synced patterns. Here editors can see all synced patterns registered for the site, edit their content, rename them, duplicate them, or delete them.
When an editor opens a synced pattern in the Patterns section and makes a change, that change propagates to every page that references the pattern. The editor sees a warning before saving: “Updating this pattern will also update all of the pages, posts, and templates that use this pattern.” This friction is intentional, synced pattern edits are high-impact actions.
From a theme developer’s perspective, this means you should communicate clearly in pattern titles and descriptions that a pattern is synced. An editor who does not understand the propagation behavior may inadvertently update site-wide content while thinking they are editing a single page. Naming conventions help: use prefixes like “Global:” or “Site-wide:” in synced pattern titles to signal their behavior at a glance.
The Site Editor also provides a list of all pages and templates that use a given synced pattern. Editors can drill down to see where the pattern appears before making changes, a safeguard that makes the sync system less intimidating once editors understand it.
Querying and Updating Synced Patterns Programmatically
Because synced patterns are wp_block posts, you can query and update them with standard WordPress APIs. This is useful for automated content pipelines, multi-site deployments, and programmatic updates triggered by external events.
A practical application: if your site’s promotional banner needs to update on a schedule (seasonal sales, quarterly announcements), you can build a WP-Cron job that updates the wp_block post content at a scheduled time. All pages displaying that synced pattern automatically show the updated content at the next render, with no editor intervention required.
Similarly, in a headless WordPress setup, synced patterns stored as wp_block posts can be queried via the REST API at /wp/v2/blocks. The rendered content endpoint (/wp/v2/blocks/42?context=view) returns the fully rendered HTML, which your frontend can consume directly without parsing Gutenberg block markup.
Partial Syncing: Global Structure, Instance-Level Content
Fully synced patterns have one limitation: every instance shows identical content. There is no way to insert the same CTA banner with different button text on different pages. Until WordPress 6.6, the choice was binary: fully synced (all instances identical) or unsynced (all instances independent).
WordPress 6.6 introduced partial syncing through the Block Bindings API. With partial syncing, you can designate specific block attributes as overridable at the instance level while keeping the rest of the pattern synced. The pattern’s layout, colors, and structure stay global. Only the bound attributes can be customized per instance.
The practical implications of partial syncing are significant. A CTA banner pattern can now have a global background color, button style, and layout, all synced, while the headline and button text are overridable per instance. This hits a sweet spot between full control and global consistency. Marketing teams get the brand-consistent wrapper; content editors get the flexibility to customize the message per page.
Partial syncing is still a newer feature and its editor UI has evolved across WordPress releases. As of 6.6+, the editor shows an “Override” option on bound attributes when an editor is viewing an instance (not editing the pattern in the Patterns library). Before 6.6, partial syncing required direct block JSON editing to set up, which limited it to developer workflows. Plan your partial syncing strategy based on the minimum WordPress version your theme supports.
Real-World Use Cases for Synced Patterns
The most effective way to see where synced patterns add value is to walk through the specific scenarios where they solve real problems that unsynced patterns or template parts cannot address as cleanly.
Promotional banners. Time-limited promotions (holiday sales, product launches, free trial offers) need to appear consistently across the homepage, landing pages, and blog posts. With an unsynced pattern, every instance needs to be manually updated when the promotion ends. With a synced pattern, one edit removes the banner everywhere.
Newsletter signup CTAs. Sites that embed email capture forms in multiple locations (end of blog posts, sidebar, dedicated landing page) benefit from a synced CTA pattern. When the offer changes (“Get our free guide” vs. “Join 10,000 subscribers”), one update refreshes every instance. The form embed code, the button style, and the legal micro-copy stay consistent.
Trust badges and certifications. Security certificates, payment badges, and compliance logos need to be identical wherever they appear. A synced pattern containing the badge grid ensures that when a new certification is added or a logo is updated, every page reflects the change automatically.
Announcement bars. A site-wide announcement (maintenance windows, major product updates, important policy changes) that sits above the header on every page is a classic synced pattern use case. The alternative, updating every page template or adding PHP to the header, is far more error-prone.
Author bios for multi-author blogs. Each author can have a synced “about me” block. When they update their bio, headshot, or social links, every post showing that author bio updates simultaneously. This is better than a PHP shortcode or a widget because it uses native block markup and is editor-manageable without code.
Recurring in-content CTAs. Long-form content that promotes a related product or service at multiple points in the article benefits from a synced CTA block. If the pricing changes, one update refreshes the CTA in every article that uses it. Without sync, every article containing that CTA needs to be individually found and edited.
Synced Patterns vs. Template Parts: Understanding the Difference
Template parts and synced patterns are both global, reusable structures. The distinction is structural versus content. Template parts define the structure of a page’s outer shell, where the header lives, how the footer is laid out, what the sidebar looks like. Synced patterns define content that appears inside that structure.
Template parts are managed in the Site Editor’s Templates section and stored as files in the parts/ directory (for the default version) or as database entries when modified. They are associated with templates and cannot be freely inserted into arbitrary page content via the inserter. The header and footer template parts guide covers this in detail.
Synced patterns are content-level reusable blocks. They can be inserted anywhere the block inserter works, pages, posts, templates, template parts. They are stored as wp_block posts. They appear in the Patterns library in the Site Editor but are also accessible in the inserter when editing regular post content.
The rule of thumb: if the reusable element is part of every page’s layout structure, use a template part. If it is a piece of content that appears in some places across the site (but not necessarily all), use a synced pattern.
Synced Patterns in the REST API
The WordPress REST API exposes synced patterns through the wp_block post type endpoint. This makes synced patterns accessible in headless architectures and useful for automated management workflows.
List all synced patterns: GET /wp/v2/blocks
Get a specific pattern: GET /wp/v2/blocks/42
Update a pattern (requires authentication): POST /wp/v2/blocks/42 with {"content": "...block markup..."}
Delete a pattern: DELETE /wp/v2/blocks/42
The rendered content endpoint is especially useful for headless setups. Adding ?context=view to the GET request returns the processed HTML rather than the raw block markup. Your decoupled frontend can consume this rendered output directly without needing to parse Gutenberg block syntax.
One security note: the wp_block post type has its own capability checks. By default, only users with edit_posts capability can create or modify synced patterns. Custom applications that need to read but not modify synced patterns should use a read-only application password or nonce with appropriate capability restrictions.
Handling Deleted Synced Patterns
When a synced pattern’s wp_block post is deleted, every page or post that references it via wp:block {"ref":ID} shows an error state in the editor: “This block has been deleted or is unavailable.” On the frontend, the reference block renders as empty, no visible output, no error for visitors.
This behavior means deleted synced patterns silently remove content from the frontend. If a promotional banner synced pattern is deleted, every page that displayed the banner now shows nothing in that slot. This is usually the desired behavior, but it is worth documenting clearly for site owners who may not realize the connection.
If you need to retire a synced pattern, replacing it across all instances with something different, the safer workflow is to edit the synced pattern content to the new version rather than deleting it and manually updating all instances. The propagation advantage works in both directions: updating is as easy as creating.
Performance Considerations
Synced patterns add one database query per unique pattern rendered on a page: WordPress fetches the wp_block post for each reference. On pages with many synced pattern instances, this can add up. Fortunately, WordPress caches wp_block posts in the object cache. Sites running a persistent object cache (Redis, Memcached) will see no meaningful performance impact from synced patterns.
Without a persistent cache, pages rendering multiple distinct synced patterns will incur one database query per unique pattern per page load. For most sites this is negligible, synced patterns are typically used for a handful of site-wide components, not dozens. But if you are building a heavily pattern-driven layout for a high-traffic site, ensure persistent object caching is enabled. This is good practice regardless, but especially relevant when the design relies heavily on synced patterns.
Multiple instances of the same synced pattern on a single page do not multiply database queries, the wp_block post is fetched once and reused for all instances on that request. If performance remains a concern at scale, page-level full-page caching (via a caching plugin or server-side configuration) eliminates the query overhead entirely, since the final rendered HTML is cached rather than generated on every request.
Migrating Reusable Blocks to Synced Patterns
If you are working on a theme that was built before WordPress 6.3 and uses the older “Reusable Block” terminology, the underlying data model is identical, both are wp_block posts. The rename from “Reusable Blocks” to “Synced Patterns” was purely nomenclatural, introduced to align with the broader pattern system.
Existing reusable blocks created before WordPress 6.3 continue to work as synced patterns without migration. The wp_pattern_sync_status post meta is absent on pre-6.3 entries, which WordPress treats as fully synced by default. No action required for existing content.
The only migration task that may arise: blocks previously created as “Unsynced” reusable blocks (which existed briefly as a feature) have wp_pattern_sync_status set to unsynced. If you want to make them fully synced, update that post meta value to an empty string or delete the meta key entirely.
Building a Synced Pattern Library Strategy
A well-structured synced pattern library starts with a clear scope definition: what content in this theme or site genuinely needs to be global? Not every reusable element should be synced. The question is whether consistency across all instances is a feature or a liability for that specific piece of content.
A practical starting point for most marketing or SaaS sites:
- 1–2 announcement or promotional banners, change frequently, need to update everywhere at once.
- A newsletter CTA block, consistent offer, consistent form embed, updates when the offer changes.
- A trust/social proof block, logos, badges, or testimonial carousel that stays consistent.
- A contact or location info block, phone number, address, hours; if it changes, it must change everywhere.
Keep the synced pattern library small and purposeful. Every synced pattern is a dependency: delete it accidentally and content disappears across the site. A library of 4–8 carefully chosen synced patterns is more maintainable than 30 patterns where half should have been unsynced.
Document each synced pattern in your theme’s documentation with its purpose, where it is used, and the update procedure. A block theme built with clear architectural boundaries between structural template parts, synced content patterns, and unsynced layout patterns is easier to hand off to editors and maintain over time.
Wrapping Up
Synced patterns fill a specific gap in the block theme toolkit: global content that needs to stay consistent and update everywhere at once. Understanding the technical model, wp_block posts, reference blocks, the seeding behavior of PHP-registered patterns, gives you the foundation to use them reliably rather than relying on trial and error in the editor.
The most important design decision is choosing what belongs in a synced pattern versus a template part versus an unsynced pattern. Get that right and the rest follows: your site has a clear layer for global structure (template parts), global content (synced patterns), and flexible per-page layouts (unsynced patterns). Editors know where to look when they need to update something, and the risk of one change inadvertently breaking something else is contained.
Partial syncing in WordPress 6.6+ adds a third option for cases where global structure with per-instance customization makes more sense than a fully uniform block. As that feature matures, the rigid line between “synced” and “unsynced” will blur into a more flexible spectrum, but the core principle remains the same: identify the right level of global control for each piece of content and configure your patterns accordingly.