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

Published 26 August 2026 by Jake at Pattern Paste.
Canonical: https://patternpaste.com/blog/add-a-block-pattern-to-wordpress/
Tags: Patterns, Tutorial, Block themes

---

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.

```html
<!-- 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
<?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
<?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:

```html
<!-- 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](/patterns/), or read [why a pattern should never state a hex](/blog/theme-json-colour-presets/).*