Block Patterns, or simply patterns, enable theme developers to create custom blocks that are compositions of blocks provided by the standard block library, and if desired, with additional design flourishes. For example, Twenty Twenty One includes support for blocks designed with overlapping images and text, among others. In the blocks version of Twenty Twenty One, these will be registered as patterns within the theme.
Repeatable design patterns
Unlike templates, patterns are defined in PHP in a way that might be more familiar to experienced theme developers. We can define them in the functions.php file of our theme, or a file that is included there.
First up, as a matter of good practice, we register a category for our patterns using the register_block_pattern_category function. By categorising our patterns, we can separate them from other patterns such as those registered by WordPress core, and other third-party plugins:
register_block_pattern_category(
'theme_blocks',
array( 'label' => esc_html__( 'Theme Blocks', 'theme-blocks' ) )
);Now we can start adding our patterns with the `register_block_pattern` function. The parameters for this function are the pattern name as a string, and an array of properties to be associated with the pattern. This array comprises a title, content, description, categories, keywords and viewport width. Putting this together, a simple pattern can be registered like this:
register_block_pattern(
'theme-blocks/pattern-name',
array(
'title' => esc_html__( 'Pattern Title', 'theme-blocks' ),
'categories' => array( 'theme-blocks' ),
'viewportWidth' => 1024,
'description' => esc_html_x( 'A description of what is in the pattern', 'Block pattern description', 'theme-blocks' ),
'content' => '<!-- wp:columns ... -->'
)
);Most of what we’re doing here is self-explanatory, however the content property may look less familiar. This property contains the raw HTML content for the pattern. What we add here follows the same convention as template parts.
Getting real
It’s easier to think about what this contains if we work with a real pattern, so let’s take Twenty Twenty One’s Overlapping Images pattern. The content looks like this:
<!-- wp:columns {"verticalAlignment":"center","align":"wide","className":"is-style-twentytwentyone-columns-overlap"} -->
<div class="wp-block-columns alignwide are-vertically-aligned-center is-style-twentytwentyone-columns-overlap">
<!-- wp:column {"verticalAlignment":"center"} -->
<div class="wp-block-column is-vertically-aligned-center">
<!-- wp:image {"align":"full","sizeSlug":"full"} -->
<figure class="wp-block-image alignfull size-full">
<img src="' . esc_url( get_template_directory_uri() ) . '/assets/images/roses-tremieres-hollyhocks-1884.jpg" alt="' . esc_attr__( '“Roses Tremieres” by Berthe Morisot', 'tt1-blocks' ) . '"/>
</figure>
<!-- /wp:image -->
<!-- wp:spacer -->
<div style="height:100px" aria-hidden="true" class="wp-block-spacer"></div>
<!-- /wp:spacer -->
<!-- wp:image {"align":"full","sizeSlug":"full"} -->
<figure class="wp-block-image alignfull size-full">
<img src="' . esc_url( get_template_directory_uri() ) . '/assets/images/in-the-bois-de-boulogne.jpg" alt="' . esc_attr__( '“In the Bois de Boulogne” by Berthe Morisot', 'tt1-blocks' ) . '"/>
</figure>
<!-- /wp:image -->
</div>
<!-- /wp:column -->
<!-- wp:column {"verticalAlignment":"center"} -->
<div class="wp-block-column is-vertically-aligned-center">
<!-- wp:spacer -->
<div style="height:100px" aria-hidden="true" class="wp-block-spacer"></div>
<!-- /wp:spacer -->
<!-- wp:image {"align":"full",sizeSlug":"full"} -->
<figure class="wp-block-image alignfull size-full">
<img src="' . esc_url( get_template_directory_uri() ) . '/assets/images/young-woman-in-mauve.jpg" alt="' . esc_attr__( '“Young Woman in Mauve” by Berthe Morisot', 'tt1-blocks' ) . '"/>
</figure>
<!-- /wp:image -->
</div>
<!-- /wp:column -->
</div>
<!-- /wp:columns -->To ease readability, we have added line breaks and indentation, but it’s worth noting that as this is ultimately just a string, when we come to registering our pattern, we can paste it in as a long line of text.
What we can see in this block is a mix of regular HTML, with the Block Editor’s pseudo HTML expressed as comments. Boiling it down, this markup contains two columns, with each one containing an image and some stylistic spacing. The images used here are just placeholders that can be modified by users in the editor, but it’s worth noting that any placeholder images used in a pattern must also be included in the theme assets.
You may note that in the markup above, it’s not entirely clear where the magic that makes these columns overlap occurs. This is achieved via a block style, and applied using the is-style-twentytwentyone-columns-overlap class.
Putting it all together
With all of this in place, here’s how we can now interact with our pattern in the site editor.
As you can see, we can find it by searching for “overlap” in the block editor. We can also browse all of our patterns in the block browser which is accessed by clicking “browse all” when selecting a block in the inline editor.
Why should I use patterns?
Hopefully this has helped you gain some understanding of what patterns are and how they work. Don’t worry if you’re still a little confused. There’s a lot to take in here and it’s something that makes more sense once you start making patterns. However, you may still be wondering why we’re talking about this and what the advantages are of using patterns.
Patterns are very helpful when users are trying to create more advanced layouts that have a greater sense of art direction than WordPress has traditionally provided. They’re a great way of breaking the monotony that can set in with long-form content, as well as helping users break the sense of creative block that is often felt when confronted with a blank page. As you can see in the patterns included with Twenty Twenty One, users have easy access to more versatile and visually interesting ways of presenting their content.
Next steps
To help consolidate your understanding, check out the full implementation of Twenty Twenty One’s patterns in the experimental block-based version of the theme.