How to Use Block Patterns in WordPress: Simple Guide

In WordPress, use block patterns to insert predefined groups of blocks into your posts or pages for faster design. You can add them via the block editor by selecting the Patterns tab or register custom patterns with register_block_pattern() in your theme or plugin.

Syntax

The main function to add custom block patterns is register_block_pattern(). It requires a unique name and an array of settings:

• name: A unique string identifier like theme/pattern-name.
• title: A human-readable name shown in the editor.
• description: A short explanation of the pattern.
• content: The HTML markup of the blocks that make up the pattern.
• categories: An array to group patterns in the editor.

php

<?php
register_block_pattern(
    'theme/example-pattern',
    array(
        'title'       => __('Example Pattern', 'theme-textdomain'),
        'description' => _x('A simple two-column layout', 'Block pattern description', 'theme-textdomain'),
        'content'     => "<!-- wp:columns -->\n<div class=\"wp-block-columns\">\n<!-- wp:column -->\n<div class=\"wp-block-column\">\n<p>Left column content</p>\n</div>\n<!-- /wp:column -->\n\n<!-- wp:column -->\n<div class=\"wp-block-column\">\n<p>Right column content</p>\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->",
        'categories'  => array('columns', 'text'),
    )
);
?>

Example

This example registers a custom block pattern with two columns, each containing a paragraph. Once registered, it appears in the block editor under the Patterns tab for easy insertion.

php

<?php
function theme_register_custom_patterns() {
    register_block_pattern(
        'theme/two-column-text',
        array(
            'title'       => __('Two Column Text', 'theme-textdomain'),
            'description' => __('Two columns with sample text', 'theme-textdomain'),
            'content'     => "<!-- wp:columns -->\n<div class=\"wp-block-columns\">\n<!-- wp:column -->\n<div class=\"wp-block-column\">\n<p>This is the left column.</p>\n</div>\n<!-- /wp:column -->\n\n<!-- wp:column -->\n<div class=\"wp-block-column\">\n<p>This is the right column.</p>\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->",
            'categories'  => array('columns'),
        )
    );
}
add_action('init', 'theme_register_custom_patterns');
?>

Output

In the WordPress block editor, under the Patterns tab, a new pattern named 'Two Column Text' appears. When inserted, it shows two side-by-side columns each with sample text.

Common Pitfalls

Common mistakes when using block patterns include:

• Not using unique names for patterns, causing conflicts.
• Incorrect HTML markup in the content string, which breaks the pattern display.
• Registering patterns too late or outside the init hook, so they don't load properly.
• Forgetting to add the pattern category, making it hard to find in the editor.

Always test your pattern markup in the editor to ensure it renders correctly.

php

<?php
// Wrong: Missing unique prefix and wrong hook
register_block_pattern(
    'two-column',
    array(
        'title' => 'Two Column',
        'content' => '<!-- wp:columns --><div><div><p>Left</p></div><div><p>Right</p></div></div><!-- /wp:columns -->'
    )
);

// Right: Use unique name and init hook
function register_my_pattern() {
    register_block_pattern(
        'mytheme/two-column',
        array(
            'title' => 'Two Column',
            'content' => "<!-- wp:columns --><div class=\"wp-block-columns\"><div class=\"wp-block-column\"><p>Left</p></div><div class=\"wp-block-column\"><p>Right</p></div></div><!-- /wp:columns -->",
            'categories' => array('columns')
        )
    );
}
add_action('init', 'register_my_pattern');
?>

Quick Reference

Tips for using block patterns effectively:

• Use register_block_pattern() inside the init hook.
• Give patterns unique names with a prefix to avoid conflicts.
• Write valid block HTML in the content string.
• Group patterns with categories for easy browsing.
• Use the Patterns tab in the block editor to insert patterns quickly.

Key Takeaways

Use register_block_pattern() inside the init hook to add custom block patterns.

Give each pattern a unique name with a prefix to avoid conflicts.

Write valid block HTML markup in the content string for proper rendering.

Assign categories to patterns to organize them in the block editor.

Insert patterns easily via the Patterns tab in the WordPress block editor.