In last month’s Builder Basics article, we explored block patterns: what they are and how you can use them. We learned that a block pattern is simply a predefined collection of blocks that forms a specific layout. We showcased the power of patterns and discussed how they are a cornerstone of modern WordPress theme development. Today we will learn how to design, share, and register our own patterns!

Please note that this article uses the Twenty Twenty-Two theme in all its examples. This block-based theme was released alongside WordPress 5.9 and is a fantastic resource featuring over 60 block patterns.

Pattern Design

The hardest part about creating a block pattern is deciding how it should look. Let’s start with something relatively simple: a grid of items, two rows of three. We could use this design to showcase different business services or product features. 

Quick Tip: Patterns can be built out of any block, including third-party blocks. However, if you intend to distribute your patterns to a broad audience, try and use only core WordPress blocks—that way, the user does not have to install additional plugins to use your designs.

For me, pattern design begins in the Editor. While patterns can be coded manually, it’s much easier to do things visually. I’ll start by adding a Columns block with three columns for the first row of the grid. Next, add Heading, Paragraph, and Buttons blocks to each column. Duplicate the Columns block to create the second grid row. Finally, I will apply a few styling configurations and wrap both Columns blocks in a Group block with a background color. The result looks like this:

You can see the 33 blocks that make up this design in the screenshot above! 

If I want to create an alternate “dark” version of the grid, I just need to duplicate the original design and tweak the styling.

While both designs are relatively simple, creating them from scratch can be tedious. Being able to share and/or save these block patterns would save lots of time.

Sharing a Design

Sharing a pattern design is easy! Say you want to move the design to another page on your website, or perhaps another website entirely. It’s as simple as copying and pasting the block markup. There are multiple ways to accomplish this. 

If the pattern design is contained in a “container” block, such as a Group, Cover, or Columns block, select the outermost container and use the tools menu to select “Copy.” The block markup is copied to the clipboard and you can paste wherever you like.

A second option is to use the Code Editor, which you can access from the Options panel.

The Code Editor provides a visual representation of all block markup on the current page or post. I prefer this method because it’s easy to see exactly what code is being copied. 

Registering a Pattern

Copy and pasting block markup might be easy, but we often want a more permanent version of our pattern designs. To do so, we will use the Patterns API to “register” a custom block pattern. This makes our design available in both the Inserter and the Pattern Explorer within WordPress. 

To register a pattern, we use the PHP function register_block_pattern(). This function accepts two parameters, a title and an array of properties. Before going through each one, let’s look at an example.

register_block_pattern(

‘example/feature-grid-light’,

array(

‘title’         => __( ‘Feature Grid – Light’, ‘textdomain’ ),

‘description’   => __( ‘Showcase six featured items in a grid on a light background.’, ‘textdomain’ ),

‘categories’    => array( ‘featured’, ‘columns’ ),

‘keywords’      => array( ‘feature’, ‘grid’ ),

‘viewportWidth’ => 1400,

‘blockTypes’    => array( ‘core/columns’ ),

‘content’       => ‘PATTERN CONTENT’

)

);

Here we are registering the Feature Grid pattern that we designed previously. The title follows a namespace/title naming convention. When registering multiple patterns in the same project, it’s best practice to keep the namespace consistent.

Only the title and content parameters in the properties array are technically required. For brevity, the pattern content is excluded in the above example. However, this is the same code we copied and pasted in the previous section. Categories are set using the categories field, and a pattern can have multiple. In the Editor, patterns are organized by category. For the remaining properties, a fantastic breakdown is provided in the Block Editor Handbook. 

To register the Feature Grid pattern with the dark background, just duplicate the registration code and update accordingly. Finally, we wrap both functions like so and place everything in the functions.php file of our theme. 

function my_pattern_library_register_block_patterns() {

register_block_pattern(

‘example/feature-grid-light’,

array( … )

);

register_block_pattern(

‘example/feature-grid-dark,

array( … )

);

}

add_action( ‘init’, ‘example_register_block_patterns’ );

The complete code is available in a Gist on GitHub.

Once the code is added, our newly registered patterns will now display in the Inserter and the Pattern Explorer. 

Registering a Pattern Category

When working with custom patterns, it’s often helpful to place them in custom categories. WordPress makes it simple with register_block_pattern_category(). This function is similar to the one we used to register patterns. All you need to do is provide a category title and an array of properties. As of WordPress 5.9, label is the only supported property, but we expect more in the future.

The following example registers the “Custom” category with the title custom. Place this code in the functions.php file of your theme alongside the pattern registration examples.

function example_register_block_pattern_categories() {

register_block_pattern_category(

‘custom’,

array( ‘label’ => __( ‘Custom’, ‘textdomain’ ) )

);

}

add_action( ‘init’, ‘example_register_block_pattern_categories’ );

Pattern categories will only be displayed in the Editor if they have patterns associated with them. Therefore, if we add custom to the two feature grid patterns we registered earlier, the “Custom” category will appear like so:

Create a Pattern Library Plugin

In the previous sections, we registered patterns and a pattern category by placing the code in the functions.php file of our theme. While this works, it’s not ideal for the long term. Suppose we need to update our theme? Perhaps we want to use the patterns on another website? 

WordPress has yet to provide a native solution for custom pattern management, so we must look to alternative solutions. Additionally, having patterns in a more portable format is often preferable. 

The best approach that I have found is to create a simple WordPress plugin to store my collection of custom patterns. Plugins provide maximum versatility and are theme agnostic. I will show you how to create your very own pattern library plugin in the following steps. 

Quick Tip: If you would like to skip the following steps, I have prepared a complete “My Pattern Library” plugin that should provide a great starting point for your own library. The code is available as a Gist on GitHub.

Step 1: Getting Setup

Before you start building the plugin, you will need a working version of WordPress and a text editor of some variety. I highly recommend Local for creating local WordPress installations and have been using it exclusively for many years. I use Atom for text editing, but there are many great options. Even the basic text editor that comes with your operating system will do. 

Set up a local WordPress site using Local or a similar application. Make sure WordPress is updated to version 5.9 or greater. Patterns will work on 5.5+, but it’s always best to use the latest version of WordPress whenever possible.

Step 2: Create the Plugin

The next thing you need to do is create the “base” of the plugin. If you are new to plugin development, have no fear. It sounds more daunting than it is.

Navigate to the wp-content → plugins directory in your local WordPress installation and create a new directory titled my-pattern-library. You can name the directory anything you like. Just replace “my-pattern-library” with your custom name in all subsequent steps. 

Inside the new wp-content → plugins → my-pattern-library directory, create a PHP file titled my-pattern-library.php. Open the file in your text editor and add the following plugin header comment to the top of the file. Don’t forget the leading

/**

 * Plugin Name:   My Pattern Library

 * Description:   A simple library of block patterns.

 * Version:           0.1.0

 * Requires at least: 5.8

 * Requires PHP:  7.0

 * Author:            Your Name

 * License:           GPL v2 or later

 * Text Domain:       my-pattern-library

 */

Feel free to change the header information as you see fit. Then save the file. You now have a fully functional WordPress plugin. Confirm it’s visible on the admin Plugins page and click “Activate.” It should look like this.

While you now have a functioning plugin, it doesn’t actually do anything. Let’s change that.

Step 3: Register Patterns and Categories

In this final step, all you need to do is copy the pattern and pattern category registration code from earlier in this article into the new plugin. We previously placed this code in the theme’s functions.php file. Now, just paste it below the header comment in your my-pattern-library.php file. 

Save the file and then navigate to the Editor in WordPress. Open the Inserter, click on the Patterns tab and choose the Custom category. You should see the two patterns registered by the plugin. 

Your pattern library is now operational! When there’s a need for new custom patterns or categories, simply add them to the plugin. A complete code example is available as a Gist on GitHub.

Before we wrap up, it’s important to mention that this example is intended for personal use. You would likely want to include more functionality if the plugin were to be distributed publicly. Localization comes to mind. That said, this tutorial demonstrates just how easy it is to create a simple plugin that stores custom block patterns. 

Wrapping up 

In this article, you learned how to design, share, and register block patterns. You have even learned how to build a simple WordPress plugin to house your very own pattern library. I strongly believe that block patterns are integral to modern theme development, and I am excited to see what the future holds. If you haven’t begun exploring patterns, I hope this article encourages you to do so. Learn WordPress is a fantastic resource for additional learning and if you have any questions, please let me know in the comments.