The Complete Guide To Block Patterns

This post is the second part of the Complete Guide on Gutenberg Block Patterns, which includes the following points:

In the first part we saw the first 4 points of all the topics covered in the guide: what is a block pattern, how to insert pre-defined patterns in your pages, and where to find and how to copy patterns that are available in some directories. There we saw that we can paste a pattern on the page we are editing, but it will not be stored in our pattern library for future use.

If we want to add a new pattern to our Gutenberg pattern library, we must create and register said pattern. It’s pretty straightforward, although you do need some basic coding skills. If this is not your case, don’t worry, as we’ll later learn how to achieve the same result without requiring any coding.

5. Create a New Pattern

To create a block pattern you must use the Block Pattern API. Specifically, the PHP function register_block_pattern(). Let’s briefly see the different steps we must follow with a simple example.

But before we start, let me add a side note. When customizing WordPress using code snippets, you should always ask yourself where you should write said snippet. Most tutorials recommend the functions.php file of your active theme, as it’s the easiest solution to get the job done, but David wrote this post on how to create a plugin to keep track of all your customizations and argued that this was a better solution.

Now, what about block patterns? You can add the definition of a new block pattern in your theme (some themes, like Twenty Twenty-One, already include their own), or you can add it in a custom plugin. I’m sure you will find defenders and detractors of both solutions, so just choose the one that better suits your needs.

#1 Design The Blocks That Will Form Your Pattern

As I already mentioned in the previous post, a pattern is a set of blocks grouped as you like. Suppose I want to create a pattern of blocks that I can use to create a section describing the basic features of a product.

To do this, on a page that I have titled “Creating a Pattern,” I start by creating a title block, “6 Features Section,” and then I insert a 3-column block.

Creating the set of blocks that will form my pattern.

In the first block I add an image and, under it, the title and description of the feature.

I copy the image, the title, and the description in the next two blocks. And finally, I duplicate this row so that I have a section that will include the description of the six features.

Set of blocks that will form my new pattern. — I have already created the set of blocks that will form my new pattern.

Of course, it only makes sense to create a block pattern if you think you are going to use it more than once.

Nelio Content

I’m so happy about Nelio Content that I will sound like a payed advocate… but here’s why you’ll love it: it works as promised, its auto-scheduling feature is top-notch, Nelio’s value for money is unmatched, and the support team feels like your own.

Panozk

WordPress.org

View Plans

#2 Copy The Content of The Blocks

Once we have defined the set of blocks, we only have to select them with the mouse and in the toolbar click on Copy.

Select and click copy. — Select the set of blocks that will make up the pattern and click copy.

#3 Escape copied HTML content

To avoid problems, we need to escape the text we’ve just copied, so that especial characters like line breaks, tab characters, and so on can be understood by the computer. You can easily escape a text using online tools such as onlinestringtools.com or JSON Escape/Unescape: just paste the code that you had previously copied and you will get a correctly escaped text.

#4 Register The Pattern

At this point, the only thing left is to use the register_block_pattern() function. This function receives two arguments: the name of the pattern and an array of properties. At the end of this post I give you more details about the properties you can define in a pattern, but first let’s see the required steps to create one.

This is our example:

register_block_pattern(
   'ruth-gutenberg-blocks-patterns/section-with-six-features',
   array(
     'title'   => __( 'Section with 6 features', 'nelio' ),
     'content' => "<!-- wp:heading {\"textAlign\":\"center\"} -->\n<h2 class=\"has-text-align-center\">6 Features Section</h2>\n<!-- /wp:heading -->\n\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\"><!-- wp:column {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-column is-vertically-aligned-center\"><!-- wp:image {\"align\":\"center\",\"id\":44,\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<div class=\"wp-block-image\"><figure class=\"aligncenter size-large\"><img src=\"http://testsite.local/wp-content/uploads/2020/12/wordpress.png\" alt=\"\" class=\"wp-image-44\"/></figure></div>\n<!-- /wp:image -->\n\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3} -->\n<h3 class=\"has-text-align-center\">Feature Heading</h3>\n<!-- /wp:heading -->\n\n<!-- wp:paragraph {\"align\":\"center\"} -->\n<p class=\"has-text-align-center\">Feature description</p>\n<!-- /wp:paragraph --></div>\n<!-- /wp:column -->\n\n<!-- wp:column {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-column is-vertically-aligned-center\"><!-- wp:image {\"align\":\"center\",\"id\":44,\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<div class=\"wp-block-image\"><figure class=\"aligncenter size-large\"><img src=\"http://testsite.local/wp-content/uploads/2020/12/wordpress.png\" alt=\"\" class=\"wp-image-44\"/></figure></div>\n<!-- /wp:image -->\n\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3} -->\n<h3 class=\"has-text-align-center\">Feature Heading</h3>\n<!-- /wp:heading -->\n\n<!-- wp:paragraph {\"align\":\"center\"} -->\n<p class=\"has-text-align-center\">Feature description</p>\n<!-- /wp:paragraph --></div>\n<!-- /wp:column -->\n\n<!-- wp:column {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-column is-vertically-aligned-center\"><!-- wp:image {\"align\":\"center\",\"id\":44,\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<div class=\"wp-block-image\"><figure class=\"aligncenter size-large\"><img src=\"http://testsite.local/wp-content/uploads/2020/12/wordpress.png\" alt=\"\" class=\"wp-image-44\"/></figure></div>\n<!-- /wp:image -->\n\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3} -->\n<h3 class=\"has-text-align-center\">Feature Heading</h3>\n<!-- /wp:heading -->\n\n<!-- wp:paragraph {\"align\":\"center\"} -->\n<p class=\"has-text-align-center\">Feature description</p>\n<!-- /wp:paragraph --></div>\n<!-- /wp:column --></div>\n<!-- /wp:columns -->\n\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\"><!-- wp:column {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-column is-vertically-aligned-center\"><!-- wp:image {\"align\":\"center\",\"id\":44,\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<div class=\"wp-block-image\"><figure class=\"aligncenter size-large\"><img src=\"http://testsite.local/wp-content/uploads/2020/12/wordpress.png\" alt=\"\" class=\"wp-image-44\"/></figure></div>\n<!-- /wp:image -->\n\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3} -->\n<h3 class=\"has-text-align-center\">Feature Heading</h3>\n<!-- /wp:heading -->\n\n<!-- wp:paragraph {\"align\":\"center\"} -->\n<p class=\"has-text-align-center\">Feature description</p>\n<!-- /wp:paragraph --></div>\n<!-- /wp:column -->\n\n<!-- wp:column {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-column is-vertically-aligned-center\"><!-- wp:image {\"align\":\"center\",\"id\":44,\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<div class=\"wp-block-image\"><figure class=\"aligncenter size-large\"><img src=\"http://testsite.local/wp-content/uploads/2020/12/wordpress.png\" alt=\"\" class=\"wp-image-44\"/></figure></div>\n<!-- /wp:image -->\n\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3} -->\n<h3 class=\"has-text-align-center\">Feature Heading</h3>\n<!-- /wp:heading -->\n\n<!-- wp:paragraph {\"align\":\"center\"} -->\n<p class=\"has-text-align-center\">Feature description</p>\n<!-- /wp:paragraph --></div>\n<!-- /wp:column -->\n\n<!-- wp:column {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-column is-vertically-aligned-center\"><!-- wp:image {\"align\":\"center\",\"id\":44,\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<div class=\"wp-block-image\"><figure class=\"aligncenter size-large\"><img src=\"http://testsite.local/wp-content/uploads/2020/12/wordpress.png\" alt=\"\" class=\"wp-image-44\"/></figure></div>\n<!-- /wp:image -->\n\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3} -->\n<h3 class=\"has-text-align-center\">Feature Heading</h3>\n<!-- /wp:heading -->\n\n<!-- wp:paragraph {\"align\":\"center\"} -->\n<p class=\"has-text-align-center\">Feature description</p>\n<!-- /wp:paragraph --></div>\n<!-- /wp:column --></div>\n<!-- /wp:columns -->",
   )
 );

As you can see in the previous snippet, we first specify a unique name to identify our pattern (ruth-gutenberg-blocks-patterns/section-with-six-features), and then we specify an array with a couple of properties: the title (“Section with 6 features”) a user of the pattern will see and the content itself. The content is the text we escaped in the step before.

#5 Create a Plugin With The Registered Pattern

To have the pattern registered in our editor, we can create a plugin or we could put it in our active theme. If you create a plugin, this is what you need:

<?php
/**
 * Plugin Name: Ruth’s Block Patterns
 * Description: My personal block patterns
 * Version: 1.0.0
 */
defined( 'ABSPATH' ) or die();
function ruth_patterns_register_block_patterns() {
   if ( ! class_exists( 'WP_Block_Patterns_Registry' ) ) {
     return;
   }
   register_block_pattern(
     'ruth-gutenberg-blocks-patterns/section-with-six-features',
     array(
       'title'    => __( 'Section with 6 features', 'nelio' ),
       'content'  => "…",
     )
   );
 }
 add_action( 'init', 'ruth_patterns_register_block_patterns' );

And voilà! If we now refresh our editor (assuming you’ve activated the plugin, of course), you’ll see the new pattern:

but, unfortunately, it’s listed under Uncathegorized. This is because we have not indicated whether our block belongs to any of the existing categories or to a new one.

#6 Add a New Category of Patterns

You can add new block patterns into existing categories, or create a completely new category using the register_block_pattern_category function. This function also takes two arguments: the name of the category and an array of options. Sounds familiar?

Here’s an example:

function ruth_patterns_register_block_pattern_category() {
   if ( ! class_exists( 'WP_Block_Patterns_Registry') ) {
     return;
   }
 register_block_pattern_category (
     'ruth-features',
     array(
       'label' => _x( 'Features', 'Block pattern category', 'nelio' )
     )
   );
 }
 add_action( 'init', 'ruth_patterns_register_block_pattern_category' );

Once the new category is ready, don’t forget to update your block pattern so that it explicitly specifies that it should be listed under this new category:

function ruth_patterns_register_block_patterns() {
   if ( ! class_exists( 'WP_Block_Patterns_Registry' ) ) {
     return;
   }
   register_block_pattern(
     'ruth-gutenberg-blocks-patterns/section-with-six-features',
     array(
       'title'      => __( 'Section with 6 features', 'nelio' ),
       'content'    => "…",
       'categories' => [ 'ruth-features' ],
     )
   );
 }
 add_action( 'init', 'ruth_patterns_register_block_patterns' );

And there you have it:

Block pattern created with the indicated category. — Block pattern created and available with the indicated category.

We can now add it to any new page we create and then make the modifications that we feel are appropriate, as you can see in the section created on a new page for the launch of our new product:

Section created with the pattern created.

Block Pattern Properties

In our example we have defined the title, content, and categories properties of a block pattern, but there are more. You will find details in the documentation that describes the register_block_pattern function, but here is a summary:

title (required): the title of the pattern.
content (required): the content of the pattern.
description: a visually hidden text used to describe the pattern in the inserter. The description is optional, but is strongly recommended when the title does not fully describe what the pattern does.
categories: a series of pattern categories used to group block patterns. Block patterns can be displayed in multiple categories.
keywords: a set of aliases or keywords that help users discover the pattern while searching.
viewportWidth: an integer that specifies the width of the pattern in the inserter.

In the case of category registration, we only have to define a label property, since there aren’t any more props.

Today we have seen that creating a pattern of blocks so that you always have it available on your website is quite easy. In the next post we will see how we can create patterns without knowing anything about code. Do not miss it!

Featured image of John Cameron on Unsplash.

The Complete Guide to Gutenberg Block Patterns (II)