Register WordPress Block Patterns with register_block_pattern in WP 5.5

WordPress 5.5 introduced Block Patterns as a core feature — pre-designed arrangements of blocks that editors can insert with a single click from the block inserter’s Patterns tab. A block pattern is just serialised Gutenberg markup (the same HTML comment syntax that lives in the database) wrapped in a PHP registration call. Once registered, the pattern appears in the editor with a live preview thumbnail, and inserting it drops the full set of blocks into the post — all fully editable. This replaces the old workflow of creating a “starter page” and duplicating it, or maintaining a library of copy-paste code snippets. Themes can ship a library of patterns covering all their key layouts — hero sections, pricing tables, testimonial grids, call-to-action banners — and users get professional-looking results without design skills.

Problem: Your theme has a hero section layout that editors keep building from scratch, getting the proportions wrong every time. You want them to insert a fully designed, pre-built hero section with one click.

Solution: Serialise the desired block markup and register it as a block pattern with register_block_pattern(). Group related patterns under a custom category with register_block_pattern_category().

<?php
add_action( 'init', 'register_my_block_patterns' );

function register_my_block_patterns() {

    // 1. Register a custom category for all theme patterns
    register_block_pattern_category( 'my-theme', [
        'label' => __( 'My Theme', 'my-theme' ),
    ] );

    // 2. Register a Hero Section pattern
    register_block_pattern(
        'my-theme/hero-section',
        [
            'title'       => __( 'Hero Section with CTA', 'my-theme' ),
            'description' => __( 'Full-width cover with heading, subheading, and button.', 'my-theme' ),
            'categories'  => [ 'my-theme', 'featured' ],
            'keywords'    => [ 'hero', 'cover', 'banner', 'cta' ],
            'content'     => '
<div class="wp-block-cover" style="min-height:500px">
  <div class="wp-block-cover__inner-container">
    <!-- wp:heading {"textAlign":"center","level":1} -->
    <h1 class="has-text-align-center">Welcome to Our Site</h1>
    <!-- /wp:heading -->
    <!-- wp:paragraph {"align":"center","textColor":"white"} -->
    <p class="has-text-align-center has-white-color has-text-color">
      Discover our products and services.
    </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">Get Started</a></div>
      <!-- /wp:button -->
    </div>
    <!-- /wp:buttons -->
  </div>
</div>
<!-- /wp:cover -->',
        ]
    );

    // 3. Unregister a core pattern you don't want in the editor
    unregister_block_pattern( 'core/social-links-shared-background-color' );
}

NOTE: The content string must contain valid serialised block markup — the same format as what WordPress stores in the database. The easiest way to create it is to build the desired layout in the Gutenberg editor, then copy the result by switching to Code Editor view (⋮ → Code editor) and copying the raw markup. Be careful with quotes — the PHP heredoc syntax (using <<<EOT ... EOT) avoids escaping issues with double-quoted attribute values in the serialised markup.