Four ways to add a block pattern to WordPress, and when to use each
Paste it, register it in a theme, ship it in a plugin, or configure a synced pattern. Implementation mechanics and trade-offs for each method.
To add a block pattern to one page, copy its block markup and paste it into the block editor. To offer it in the inserter on a site, add a PHP file to the theme's patterns/ folder or call register_block_pattern in a plugin. To keep every copy on a site in step, save it as a synced pattern.
WordPress patterns enter a site through four distinct mechanisms: pasting raw HTML into the editor, registering PHP pattern files in a block theme, calling register_block_pattern in a plugin, or saving a synced pattern to the database.
Each method solves a different distribution challenge, demands a different level of technical setup, and leaves different maintenance liabilities as the website evolves over years.
1. Direct paste into the block editor#
You can copy raw block comments and HTML directly to your clipboard and paste them into the WordPress editor canvas. The block parser instantiates the blocks immediately on paste.
<!-- wp:group {"align":"full","layout":{"type":"constrained"}} -->
<div class="wp-block-group alignfull">
<!-- wp:heading {"textAlign":"center","level":2} -->
<h2 class="wp-block-heading has-text-align-center">What we deliver</h2>
<!-- /wp:heading -->
<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">Clean core markup that inherits your active theme tokens immediately.</p>
<!-- /wp:paragraph -->
</div>
<!-- /wp:group -->
- When to use: One-off page layouts, bespoke landing pages, and rapid section prototyping where you do not need an entry in the inserter.
- Trade-off: Zero in-editor discovery. Content authors cannot browse the pattern from the plus button inside WordPress; updating a pasted section across multiple pages requires editing each post manually.
- Operational advantage: Complete autonomy. The page carries zero plugin dependencies and zero theme locks. If you change themes or deactivate helper tools tomorrow, the published page remains intact because the database stores pure, standard core blocks.
2. File-based theme patterns#
In modern block themes, WordPress automatically discovers and registers pattern files located inside the theme's root patterns/ directory. You do not need to register action hooks in functions.php; you simply create a PHP file such as patterns/cta-band.php:
<?php
/**
* Title: Call to action band
* Slug: mytheme/cta-band
* Categories: call-to-action, featured
* Description: A full-width band with a heading, supporting text and action button.
* Inserter: yes
*/
?>
<!-- wp:group {"align":"full","layout":{"type":"constrained"}} -->
<div class="wp-block-group alignfull">
<!-- wp:heading {"textAlign":"center","level":2} -->
<h2 class="wp-block-heading has-text-align-center">Ready when you are</h2>
<!-- /wp:heading -->
<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
<div class="wp-block-buttons">
<!-- wp:button -->
<div class="wp-block-button"><a class="wp-block-button__link wp-element-button" href="/contact">Get in touch</a></div>
<!-- /wp:button -->
</div>
<!-- /wp:buttons -->
</div>
<!-- /wp:group -->
WordPress parses the docblock header to register the title, namespace slug, and inserter categories. To hide internal structural patterns (like template sections) from the general editor inserter, set Inserter: no.
- When to use: Patterns tied directly to a theme's visual identity and distributed within a custom block theme repository.
- Trade-off: Bound to the active theme. Switching themes removes the pattern from the inserter, though previously inserted instances in
post_contentcontinue to render without issue.
3. Programmatic plugin registration#
To maintain patterns across theme changes or distribute an agency pattern library across multiple client installations, register patterns inside a custom plugin using register_block_pattern on the init action hook:
<?php
/**
* Plugin Name: Agency Starter Patterns
* Description: Registers curated core block patterns across all client sites.
*/
add_action( 'init', function () {
register_block_pattern_category(
'agency-curated',
array( 'label' => __( 'Curated Sections', 'agency' ) )
);
register_block_pattern(
'agency/hero-split',
array(
'title' => __( 'Editorial Split Hero', 'agency' ),
'categories' => array( 'agency-curated' ),
'content' => file_get_contents( __DIR__ . '/patterns/hero-split.html' ),
'viewportWidth' => 1200,
)
);
} );
Storing the markup in an external .html file allows clean version control diffs and lets developers test adjustments by copying and pasting directly into a local editor canvas.
- When to use: Multi-site networks, agency starter stacks, and reusable commercial pattern libraries.
- Trade-off: Adds an active plugin dependency. If an administrator deactivates the plugin, the pattern disappears from the inserter, though previously saved pages remain unaffected.
Here is an example of a service menu combining structured core blocks with scoped styles and a sliding choice of offers:
4. Synced patterns with instance overrides#
Synced patterns (formerly reusable blocks) do not duplicate static HTML markup across posts. WordPress saves the layout once in a dedicated wp_block post record and writes an ID reference to the calling page:
<!-- wp:block {"ref":214} /-->
When an editor modifies this pattern in the Site Editor, every page referencing that ID updates immediately.
With synced pattern overrides, developers can lock the container structure while allowing authors to override specific headings, paragraphs, and buttons on a per-instance basis. The master pattern continues to control margins, padding, and colours, while individual pages display customized copy.
- When to use: Global headers, recurring callouts, office hours, and legal disclaimers that must stay identical across all instances.
- Trade-off: Layouts cannot be restructured on a per-page basis without detaching the pattern. Deleting the source pattern from the Site Editor removes the section across all referencing pages simultaneously.
Restricting patterns to specific post types#
By default, registered block patterns appear in the inserter across all post types. For bespoke editorial sites, exposing a pricing grid or full-width sales hero inside a standard blog post or news update clutters the editor.
You can restrict pattern visibility to specific post types using the postTypes configuration parameter:
In a theme pattern docblock:
<?php
/**
* Title: Case Study Overview
* Slug: mytheme/case-study-overview
* Post Types: page, case_study
*/
?>
In programmatic plugin registration:
register_block_pattern(
'agency/case-study-overview',
array(
'title' => __( 'Case Study Overview', 'agency' ),
'postTypes' => array( 'page', 'case_study' ),
'content' => file_get_contents( __DIR__ . '/patterns/case-study.html' ),
)
);
Authors editing regular blog posts will never see the pattern in their inserter, keeping the writing interface focused on editorial content.
Managing pattern caching during development#
WordPress caches registered block patterns in a database transient (_wp_block_patterns_cache_ followed by the theme stylesheet name) to avoid scanning the filesystem on every request.
During local development or agency prototyping, this caching mechanism can cause confusion when newly added files or edits to patterns/*.php do not appear in the editor.
To clear the pattern cache during active development:
- Enable WP_DEBUG: When
WP_DEBUGis set totrueinwp-config.php, WordPress bypasses the pattern transient cache. - Clear the transient with WP-CLI: ``
bash # Flush theme pattern transients immediately wp transient delete --all`` - Bump theme version: In production deployments, bumping the version string in
style.cssautomatically invalidates stale pattern caches.
Persistence and lifecycle comparison#
| Method | Storage location | Survives theme switch | Per-page editable | Deletion impact |
|---|---|---|---|---|
| Direct paste | post_content | Yes | Yes | None on published pages |
| Theme pattern | patterns/*.php | Inserter removed | Yes | None on published pages |
| Plugin pattern | register_block_pattern | Inserter removed | Yes | None on published pages |
| Synced pattern | wp_block post record | Yes | Overrides only | Removes section site-wide |
The first three methods serialise independent HTML into post records. If the source file or plugin is subsequently deleted, published posts render without broken references.
Authoring portable pattern markup#
Regardless of your chosen delivery method, patterns should avoid inline hex codes and hardcoded font families. Using theme.json preset slugs ensures that patterns inherit active theme palettes automatically when inserted:
<!-- wp:group {"backgroundColor":"contrast","textColor":"base"} -->
By avoiding hardcoded styling, your patterns remain truly portable across different themes, child themes, and brand variations.
Pattern Paste provides 542 block patterns designed to inherit active block theme styles automatically, with 64 free to copy. Browse the catalogue, or read why a pattern should never state a hex.
From the library






