Register Custom Block Patterns in WordPress via PHP (2026 Guide)

Block patterns are reusable block compositions that appear in the editor’s pattern picker. You can register them via PHP (register_block_pattern()), via JSON files in /patterns/ of a block theme, or as synced patterns (the old reusable-blocks) via the Site Editor. Each path has trade-offs. This snippet covers all three, explains when to pick which, and ships five production-ready example patterns you can drop in.

I’ve built block patterns three different ways over the last four years, and every time I told myself “this time, I’ll finally pick the right one”. The honest answer is that you need all three — different patterns belong in different places. A client’s brand-specific hero section lives in a theme’s /patterns/ folder because it travels with the theme. A generic “pricing table” I reuse across 15 sites is registered via PHP in a site-agnostic mu-plugin. A synced pattern is right for a marketing team that wants to edit once and propagate to 200 pages. The examples below show each approach at the minimum viable quality — enough detail to ship, enough cross-references to understand the trade-offs.

What this snippet covers

• PHP registration — register_block_pattern() with title, description, category, keywords, block-types context, and the block markup itself
• JSON / theme-file registration — the modern block-theme approach where patterns live as .php files in /patterns/ and auto-register
• Synced patterns (ex-reusable-blocks) — when and how to use, how they differ from the other two
• Pattern categories — registering your own categories so your patterns group cleanly in the pattern picker
• 5 production-ready example patterns — hero, pricing, testimonials, FAQ, call-to-action — using core blocks only so they work on any theme
• Contextual patterns — patterns scoped to specific post types via the postTypes parameter (useful for CPTs)
• Pattern-only categories in the picker — hiding the default “Featured” / “About” clutter if you only want your branded patterns visible
• WP-CLI commands to list registered patterns and debug which are actually loading

Install and use

Drop the mu-plugin block below into wp-content/mu-plugins/gt-patterns.php. For the theme-file approach, create a /patterns/ folder in your active theme and save each pattern as a separate .php file — WordPress 6.0+ auto-registers every file in that folder. For synced patterns, no code needed — create them in the Site Editor under Patterns → Manage my patterns.

<?php
/**
 * Plugin Name: GT Custom Block Patterns
 * Description: PHP-registered patterns + custom categories. Pair with theme /patterns/ files.
 */
defined( 'ABSPATH' ) || exit;

/* ============================================================
 * 1. Register a custom pattern category first
 *    (patterns registered against a non-existent category silently land in "Uncategorized")
 * ============================================================ */
add_action( 'init', function () {
    register_block_pattern_category( 'gt-brand', [
        'label' => __( 'Gaurav Tiwari' ),
    ] );
    register_block_pattern_category( 'gt-ctas', [
        'label' => __( 'Call to Action' ),
    ] );
} );

/* ============================================================
 * 2. Register a PHP-defined pattern (simple, always works)
 * ============================================================ */
add_action( 'init', function () {
    if ( ! function_exists( 'register_block_pattern' ) ) return;

    /* Hero with headline + subhead + two buttons */
    register_block_pattern( 'gt/hero-simple', [
        'title'       => __( 'Hero — Headline + Two CTAs' ),
        'description' => __( 'Centered hero section with a bold headline, supporting line, and two call-to-action buttons.' ),
        'categories'  => [ 'gt-brand' ],
        'keywords'    => [ 'hero', 'landing', 'cta', 'headline' ],
        'content'     => '<!-- wp:group {"align":"full","layout":{"type":"constrained"}} -->
<div class="wp-block-group alignfull" style="padding:5rem 1rem;text-align:center">
  <!-- wp:heading {"level":1,"style":{"typography":{"fontSize":"3rem","lineHeight":"1.1"}}} -->
  <h1 style="font-size:3rem;line-height:1.1">Build better WordPress sites</h1>
  <!-- /wp:heading -->
  <!-- wp:paragraph -->
  <p>Production-ready snippets and tooling from 16+ years of practice.</p>
  <!-- /wp:paragraph -->
  <!-- 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" href="/code/">Browse snippets</a></div><!-- /wp:button -->
    <!-- wp:button {"className":"is-style-outline"} --><div class="wp-block-button is-style-outline"><a class="wp-block-button__link" href="/about/">About me</a></div><!-- /wp:button -->
  </div>
  <!-- /wp:buttons -->
</div>
<!-- /wp:group -->',
    ] );

    /* Pricing table — 3 columns */
    register_block_pattern( 'gt/pricing-3col', [
        'title'       => __( 'Pricing — 3 Tiers' ),
        'description' => __( 'Three-column pricing table with tier labels, prices, feature lists, and CTAs.' ),
        'categories'  => [ 'gt-brand' ],
        'keywords'    => [ 'pricing', 'tiers', 'plans' ],
        'content'     => '<!-- wp:columns --><div class="wp-block-columns">
  <!-- wp:column --><div class="wp-block-column">
    <!-- wp:heading {"level":3} --><h3>Starter</h3><!-- /wp:heading -->
    <!-- wp:heading {"level":2} --><h2>$9/mo</h2><!-- /wp:heading -->
    <!-- wp:list --><ul><li>Feature one</li><li>Feature two</li></ul><!-- /wp:list -->
  </div><!-- /wp:column -->
  <!-- wp:column --><div class="wp-block-column">
    <!-- wp:heading {"level":3} --><h3>Pro</h3><!-- /wp:heading -->
    <!-- wp:heading {"level":2} --><h2>$29/mo</h2><!-- /wp:heading -->
    <!-- wp:list --><ul><li>Everything in Starter</li><li>Feature three</li></ul><!-- /wp:list -->
  </div><!-- /wp:column -->
  <!-- wp:column --><div class="wp-block-column">
    <!-- wp:heading {"level":3} --><h3>Team</h3><!-- /wp:heading -->
    <!-- wp:heading {"level":2} --><h2>$99/mo</h2><!-- /wp:heading -->
    <!-- wp:list --><ul><li>Everything in Pro</li><li>5 seats</li></ul><!-- /wp:list -->
  </div><!-- /wp:column -->
</div><!-- /wp:columns -->',
    ] );

    /* CTA band scoped to the "post" post type only */
    register_block_pattern( 'gt/cta-newsletter', [
        'title'       => __( 'CTA — Newsletter Signup' ),
        'description' => __( 'Full-width newsletter signup block. Use at the end of blog posts.' ),
        'categories'  => [ 'gt-ctas' ],
        'keywords'    => [ 'cta', 'newsletter', 'email', 'signup' ],
        'postTypes'   => [ 'post' ], /* Only appears in pattern picker when editing a post */
        'content'     => '<!-- wp:group {"align":"full"} --><div class="wp-block-group alignfull" style="padding:3rem 1rem;background:#f4f4f4;text-align:center">
  <!-- wp:heading {"level":3} --><h3>Want more snippets?</h3><!-- /wp:heading -->
  <!-- wp:paragraph --><p>Weekly email. 800 WordPress developers read it. No spam.</p><!-- /wp:paragraph -->
  <!-- wp:buttons --><div class="wp-block-buttons"><!-- wp:button --><div class="wp-block-button"><a class="wp-block-button__link" href="/newsletter/">Subscribe</a></div><!-- /wp:button --></div><!-- /wp:buttons -->
</div><!-- /wp:group -->',
    ] );
} );

/* ============================================================
 * 3. Optional — remove WP's default patterns to keep the picker clean
 *    Comment out if you want core patterns too
 * ============================================================ */
add_filter( 'should_load_remote_block_patterns', '__return_false' );

/* ============================================================
 * 4. Optional — WP-CLI helper to list patterns
 *     wp gt-patterns
 * ============================================================ */
if ( defined( 'WP_CLI' ) && WP_CLI ) {
    WP_CLI::add_command( 'gt-patterns', function () {
        $registry = WP_Block_Patterns_Registry::get_instance();
        foreach ( $registry->get_all_registered() as $p ) {
            WP_CLI::log( sprintf( '%-40s %s', $p['name'], $p['title'] ) );
        }
    } );
}

How the three approaches compare

PHP registration via register_block_pattern() is the most explicit. Patterns are defined in code, versioned in Git, portable across themes. Use when the pattern is site-agnostic and reused across multiple projects — pricing tables, CTA bands, author boxes. Downsides: the content is a single string with escaped newlines, hard to edit, hard to preview until registered. Theme file registration (WordPress 6.0+) uses the /patterns/ folder of a block theme, one .php file per pattern with a standard header block. WordPress auto-discovers and registers them on theme load. Use for theme-specific patterns that should travel with the theme — brand heroes, section layouts unique to the design. Downsides: tied to the active theme; switch themes and the patterns are gone. Synced patterns (formerly reusable blocks) are created by users in the Site Editor. They’re stored as wp_block posts in the database. Changes propagate to every post that uses them. Use for content that multiple pages share and that needs to update in unison — a product announcement banner, a disclaimer, a testimonial you want to edit once and have updated everywhere. Downsides: users can break them by editing; they don’t version-control with code. My rule: brand-specific and pages → theme files. Site-agnostic and reusable → PHP. Content that propagates → synced. All three can coexist; the picker shows them with a small icon distinguishing type.

Download and source

• Full mu-plugin with the 5 patterns + category registration: gist.github.com/wpgaurav — search gt-patterns
• Bundled in the Functionalities plugin
• WordPress core docs: Block Patterns + Block Pattern registration API
• Theme-file auto-registration docs: block-pattern file header reference
• For full FSE pattern management without code: the Site Editor → Patterns panel — create, categorise, mark as synced, all from the UI

FAQs

Related snippets

• Lock patterns so clients can’t break them
• Restrict blocks per user role
• Add brand palette to theme.json programmatically