Block patterns are one of the most practical features in the WordPress block editor. They let you save a combination of blocks as a reusable design that editors can insert from the pattern picker without rebuilding layouts from scratch. Here is how to create custom patterns for your theme or plugin.

What Block Patterns Are

A block pattern is a pre-configured group of blocks with specific content, layout, and styling. When an editor inserts a pattern, they get the complete block structure with placeholder content they can edit. Patterns appear in the block inserter under Patterns.

WordPress ships with core patterns (hero sections, call-to-action blocks, testimonials). You can register custom patterns that match your site’s design and content types.

Registering a Simple Block Pattern in functions.php

function wpwizzy_register_block_patterns() {
    register_block_pattern(
        'wpwizzy/hero-section',
        array(
            'title'       => 'Hero Section',
            'description' => 'Full-width hero with heading, text, and a button.',
            'categories'  => array( 'featured' ),
            'content'     => '


Your Compelling Headline Here


A short description that explains what you do and who you help.



Get Started


',
        )
    );
}
add_action( 'init', 'wpwizzy_register_block_patterns' );

Getting the Block Pattern Content String

The hardest part of registering patterns is getting the block markup string. The easiest way is to build the pattern in the block editor first, then copy the block markup. In the editor, select the blocks you want, open the Options menu (three dots), and choose Copy blocks. This copies the serialised block markup to your clipboard. Paste it as the content value in your register_block_pattern call (escaping quotes as needed).

Registering a Pattern Category

Custom patterns can be assigned to custom categories to organise them in the pattern picker:

function wpwizzy_register_pattern_categories() {
    register_block_pattern_category(
        'wpwizzy',
        array( 'label' => 'WPWizzy Patterns' )
    );
}
add_action( 'init', 'wpwizzy_register_pattern_categories' );

Then use ‘wpwizzy’ in the categories array when registering your patterns.

Using a patterns/ Directory (Theme Approach)

In WordPress 6.0 and above, block themes can register patterns automatically using a patterns/ directory in the theme folder. Create a PHP file in this directory for each pattern:

<?php
/**
 * Title: Call to Action
 * Slug: wpwizzy/cta
 * Categories: featured
 */
?>
<!-- wp:group {"align":"full"} -->
<div class="wp-block-group alignfull">
<!-- wp:heading -->
<h2 class="wp-block-heading">Ready to get started?</h2>
<!-- /wp:heading -->
</div>
<!-- /wp:group -->

WordPress automatically registers files in the patterns/ directory as block patterns. No PHP registration function is needed.

Locking Patterns to Prevent Accidental Edits

Patterns can be partially locked to prevent editors from restructuring the layout while still allowing content editing. Add a lock attribute to the container block:

...

This prevents the group from being moved or deleted while still allowing blocks inside it to be edited. Useful for structured layouts where you want editors to fill in content without changing the design.

For custom block development — full custom blocks with PHP, JavaScript, and CSS — a WordPress developer can build blocks tailored to your specific content requirements.