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

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#

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, or read why a pattern should never state a hex.