Four ways to add a block pattern to WordPress, and when to use each, Pattern Paste

Canonical: https://patternpaste.com/blog/add-a-block-pattern-to-wordpress/

Blog (https://patternpaste.com/blog/) Tutorial

# 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.

Jake 26 August 2026 3 min read

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 problem and leaves different maintenance liabilities.

## 1. Direct paste into the block editor#

You can copy raw block comments and HTML directly to your clipboard and paste them into the 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 do</h2>
<!-- /wp:heading -->
<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">Three sentences, then the thing you want them to click.</p>
<!-- /wp:paragraph -->
</div>
<!-- /wp:group -->

- When to use: One-off page layouts and quick section prototyping where you do not need an entry in the inserter.

- Trade-off: Zero in-editor discovery. Updating a pasted section across multiple pages requires editing each post manually.

## 2. File-based theme patterns#

In block themes, WordPress automatically discovers and registers files inside the root patterns/ directory. You do not need to register hooks in functions.php; create a 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 and one button.
 */
?>
<!-- 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 -->
</div>
<!-- /wp:group -->

WordPress parses the docblock header to register the title, namespace slug, and inserter categories. To hide internal template parts from the 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: Tied to the active theme. Switching themes removes the pattern from the inserter, though previously inserted instances in post_content remain unaffected.

## 3. Programmatic plugin registration#

To maintain patterns across theme changes or distribute a pattern library across multiple client installations, register patterns in a plugin using register_block_pattern on init:

<?php
/**
 * Plugin Name: Acme Patterns
 */
add_action( 'init', function () {
    register_block_pattern_category( 'acme', array( 'label' => __( 'Acme', 'acme' ) ) );
    register_block_pattern(
        'acme/cta-band',
        array(
            'title'      => __( 'Call to action band', 'acme' ),
            'categories' => array( 'acme' ),
            'content'    => file_get_contents( __DIR__ . '/patterns/cta-band.html' ),
        )
    );
} );

Storing the markup in a separate .html file allows clean version control diffs and lets you test adjustments by pasting directly into an editor canvas.

- When to use: Multi-site networks, agency starter setups, and reusable section libraries.

- Trade-off: Adds an active plugin dependency that administrators must keep active. Deactivating the plugin removes inserter options but leaves published pages intact.

## 4. Synced patterns for global updates#

Synced patterns (formerly reusable blocks) do not duplicate static HTML across posts. WordPress saves the markup once in a dedicated wp_block post record and writes an ID reference to the calling page:

<!-- wp:block {"ref":214} /-->

When you edit a synced pattern in the Site Editor, every page referencing that ID updates instantly.

- When to use: Global notices, office hours, and legal disclaimers that must stay identical across all instances.

- Trade-off: Layouts cannot be adjusted on a per-page basis without detaching the pattern first. Deleting the source pattern from the Site Editor breaks every page referencing that ID.

## Persistence comparison#

Method | Source storage | 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 | No (global) | 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 delivery method, patterns should avoid inline hex codes and hardcoded font families. Using theme.json preset slugs ("backgroundColor":"contrast", "style":{"color":{"background":"var(--wp--preset--color--primary)"}}) ensures that patterns inherit active theme palettes automatically when inserted.

Pattern Paste is a library of 232 block patterns designed to inherit active block theme styles automatically, with 6 free to copy. Browse the catalogue (https://patternpaste.com/patterns/), or read why a pattern should never state a hex (https://patternpaste.com/blog/theme-json-colour-presets/).

Patterns (https://patternpaste.com/blog/tag/patterns/)Tutorial (https://patternpaste.com/blog/tag/tutorial/)Block themes (https://patternpaste.com/blog/tag/block-themes/)

Try the whole library

### £70 a year Save £50 against paying monthly

All 232 patterns and every variation, every theme download and everything we release next. What you copy is yours to keep.

Start free trial three days of full access on sign-up, no card. No automatic charge. (https://patternpaste.com/account/#plan)

## Read next

- Why does my WordPress block pattern look different from the demo? Find out which differences come from your WordPress theme, which reveal a broken pattern, and what to check before adding another CSS override. (https://patternpaste.com/blog/why-block-patterns-look-different-from-demo/) 6 September 2026

- Where block patterns come from, and what each source leaves in your page The pattern directory, your theme, a library plugin or a copy-paste catalogue: what each source puts in post_content, and what survives when it goes away. (https://patternpaste.com/blog/where-block-patterns-come-from/) 31 August 2026

All posts (https://patternpaste.com/blog/)