Custom WordPress Block Patterns: Complete Guide

Block patterns revolutionize WordPress content creation by providing pre-designed layouts users can insert with one click. This guide shows you how to create custom patterns that accelerate workflow, maintain design consistency, and empower non-technical users.

What Are Block Patterns?

Block patterns are pre-configured collections of blocks arranged into ready-to-use designs. Unlike reusable blocks (synchronized across posts), patterns insert independent copies—users can modify them freely without affecting other instances.

Patterns bridge the gap between full-page templates and individual blocks, offering flexible starting points for common layouts like hero sections, testimonials, pricing tables, and calls-to-action.

Creating Your First Custom Pattern

function register_custom_patterns() {
    register_block_pattern(
        'myplugin/hero-section',
        array(
            'title'       => 'Hero Section',
            'description' => 'Eye-catching hero with heading, text, and button',
            'categories'  => array( 'featured' ),
            'content'     => '<!-- wp:cover {"url":"https://example.com/hero.jpg","dimRatio":50} -->
                <div class="wp-block-cover">
                    <span aria-hidden="true" class="wp-block-cover__background has-background-dim"></span>
                    <img class="wp-block-cover__image-background" src="https://example.com/hero.jpg" />
                    <div class="wp-block-cover__inner-container">
                        <!-- wp:heading {"level":1} -->
                        <h1>Welcome to Our Site</h1>
                        <!-- /wp:heading -->

                        <!-- wp:paragraph -->
                        <p>Discover amazing products and services.</p>
                        <!-- /wp:paragraph -->

                        <!-- wp:buttons -->
                        <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 -->',
        )
    );
}
add_action( 'init', 'register_custom_patterns' );

Getting Block Markup

The easiest way to create pattern content is building it in the editor, then copying the markup:

Create your design in the editor
Switch to Code Editor (⋮ menu → Code editor)
Copy the HTML comments and blocks
Paste into the content property

Creating Pattern Categories

Organize patterns with custom categories:

function register_pattern_categories() {
    register_block_pattern_category(
        'business',
        array( 'label' => 'Business' )
    );

    register_block_pattern_category(
        'marketing',
        array( 'label' => 'Marketing' )
    );
}
add_action( 'init', 'register_pattern_categories' );

Advanced Pattern Properties

Enhance patterns with additional properties:

register_block_pattern(
    'myplugin/testimonial',
    array(
        'title'       => 'Testimonial Card',
        'description' => 'Customer testimonial with quote and attribution',
        'categories'  => array( 'text', 'business' ),
        'keywords'    => array( 'review', 'quote', 'customer' ),
        'viewportWidth' => 800,
        'blockTypes'  => array( 'core/column' ), // Show pattern only for specific blocks
        'content'     => '<!-- pattern markup -->'
    )
);

Testimonial Pattern Example

register_block_pattern(
    'myplugin/testimonial-card',
    array(
        'title' => 'Testimonial Card',
        'categories' => array( 'text' ),
        'content' => '<!-- wp:group {"style":{"border":{"width":"1px","style":"solid","color":"#e5e5e5"},"spacing":{"padding":{"top":"2rem","right":"2rem","bottom":"2rem","left":"2rem"}}}} -->
            <div class="wp-block-group">
                <!-- wp:paragraph {"fontSize":"large"} -->
                <p class="has-large-font-size">"This product changed my business completely. Highly recommended!"</p>
                <!-- /wp:paragraph -->

                <!-- wp:separator -->
                <hr class="wp-block-separator" />
                <!-- /wp:separator -->

                <!-- wp:paragraph -->
                <p><strong>John Doe</strong><br>CEO, Example Company</p>
                <!-- /wp:paragraph -->
            </div>
            <!-- /wp:group -->',
    )
);

Pricing Table Pattern

register_block_pattern(
    'myplugin/pricing-table',
    array(
        'title' => 'Pricing Table - Three Column',
        'categories' => array( 'business' ),
        'content' => '<!-- wp:columns -->
            <div class="wp-block-columns">
                <!-- wp:column {"style":{"border":{"width":"2px"}}} -->
                <div class="wp-block-column">
                    <!-- wp:heading {"textAlign":"center"} -->
                    <h2 class="has-text-align-center">Basic</h2>
                    <!-- /wp:heading -->

                    <!-- wp:paragraph {"align":"center","fontSize":"large"} -->
                    <p class="has-text-align-center has-large-font-size"><strong>$9/month</strong></p>
                    <!-- /wp:paragraph -->

                    <!-- wp:list -->
                    <ul><li>Feature 1</li><li>Feature 2</li><li>Feature 3</li></ul>
                    <!-- /wp:list -->

                    <!-- 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">Choose Plan</a></div>
                        <!-- /wp:button -->
                    </div>
                    <!-- /wp:buttons -->
                </div>
                <!-- /wp:column -->

                <!-- wp:column {"style":{"border":{"width":"2px"}}} -->
                <div class="wp-block-column">
                    <!-- wp:heading {"textAlign":"center"} -->
                    <h2 class="has-text-align-center">Pro</h2>
                    <!-- /wp:heading -->

                    <!-- wp:paragraph {"align":"center","fontSize":"large"} -->
                    <p class="has-text-align-center has-large-font-size"><strong>$29/month</strong></p>
                    <!-- /wp:paragraph -->

                    <!-- wp:list -->
                    <ul><li>Everything in Basic</li><li>Feature 4</li><li>Feature 5</li></ul>
                    <!-- /wp:list -->

                    <!-- 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">Choose Plan</a></div>
                        <!-- /wp:button -->
                    </div>
                    <!-- /wp:buttons -->
                </div>
                <!-- /wp:column -->

                <!-- wp:column {"style":{"border":{"width":"2px"}}} -->
                <div class="wp-block-column">
                    <!-- wp:heading {"textAlign":"center"} -->
                    <h2 class="has-text-align-center">Enterprise</h2>
                    <!-- /wp:heading -->

                    <!-- wp:paragraph {"align":"center","fontSize":"large"} -->
                    <p class="has-text-align-center has-large-font-size"><strong>Custom</strong></p>
                    <!-- /wp:paragraph -->

                    <!-- wp:list -->
                    <ul><li>Everything in Pro</li><li>Premium Support</li><li>Custom Integration</li></ul>
                    <!-- /wp:list -->

                    <!-- 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">Contact Us</a></div>
                        <!-- /wp:button -->
                    </div>
                    <!-- /wp:buttons -->
                </div>
                <!-- /wp:column -->
            </div>
            <!-- /wp:columns -->',
    )
);

Unregistering Core Patterns

Remove unwanted patterns:

function remove_core_patterns() {
    unregister_block_pattern( 'core/query-standard-posts' );
    unregister_block_pattern( 'core/query-medium-posts' );
}
add_action( 'init', 'remove_core_patterns' );

Pattern Best Practices

Use placeholder images for visual patterns
Include descriptive keywords for searchability
Test across themes to ensure compatibility
Keep patterns focused – one purpose per pattern
Add helpful descriptions explaining pattern use cases
Use semantic HTML for accessibility
Consider mobile responsiveness in layouts

Translatable Patterns

Make pattern text translatable:

'content' => sprintf(
    '<!-- wp:heading --><h2>%s</h2><!-- /wp:heading -->
    <!-- wp:paragraph --><p>%s</p><!-- /wp:paragraph -->',
    esc_html__( 'Welcome', 'textdomain' ),
    esc_html__( 'This is sample content.', 'textdomain' )
)

Organizing Patterns in Plugins

Structure patterns in separate files:

// patterns/hero.php
<?php
return array(
    'title' => 'Hero Section',
    'categories' => array( 'featured' ),
    'content' => '<!-- pattern content -->'
);

// functions.php
function register_pattern_library() {
    $patterns = glob( get_template_directory() . '/patterns/*.php' );

    foreach ( $patterns as $pattern_file ) {
        $pattern = require $pattern_file;
        $slug = basename( $pattern_file, '.php' );

        register_block_pattern( 'mytheme/' . $slug, $pattern );
    }
}
add_action( 'init', 'register_pattern_library' );

Conclusion

Block patterns transform WordPress content creation by providing professional design starting points. Start with simple patterns for common layouts, organize them into logical categories, and progressively build a pattern library tailored to your site’s needs. Well-designed patterns empower users to create beautiful pages without design expertise.

External Links

Call to Action

Streamline your workflow! Block Editor Navigator Pro provides instant block navigation, search, and organization. Find any block in seconds—try it free!