Introduction to block patterns

The code examples and images for the patterns in this lesson can be found in the GitHub repository.


A block pattern, is a group of blocks, that have been combined together, to create a layout element.

With the release of WordPress 5.5, block patterns are no longer experimental,
and they are part of WordPress core.

If you are using an earlier WordPress version, you need to install and activate the Gutenberg plugin. You do not need to enable the full site editing experiment for
block patterns to work.

Block patterns are not as advanced as custom blocks, so they are easier to create. But, they are also more limited.

Patterns can combine core blocks or blocks from plugins, but they do not have any additional controls.

There are many use cases for block patterns.
Because they can be reused and placed anywhere, and because they can be styled using the Gutenberg controls, a pattern offers more flexibility than for example a customizer option. And I believe that to some extent, it will replace the customizer.

You could create an advanced author profile, a service section from a column block, or define sections for a store, using e-commerce blocks and the cover block.

By combining block patterns with unique additional CSS classes,
variations and custom block styles, you can style and create many different sections with different purposes for your theme.

Block patterns included with WordPress 5.5

[Screen: An animation shows the default block patterns, in the patterns tab inside the block editor.]

WordPress 5.5 comes with a couple of block patterns already installed and ready to use. You can find the patterns in the editor by using the search,
or in the block patterns tab in the add block menu.

The core patterns are basic. You will find patterns for buttons and patterns designed to help users get started with the columns block.

You can place multiple copies of the same pattern in the same post or page.
Once a pattern is added in the editor, they are now individual blocks that can be moved, edited, or replaced. In a sense, the pattern stops being a pattern,
as soon as it is placed in the editor.

Another benefit, is that because the patterns are only blocks, the content is always saved, even if the user switches themes.

Having said that, it might look different in different themes.

[Screen: A default block pattern with black text is placed in a post with a dark grey background, illustrating that patterns need to be tested with different kinds of themes.]
I suggest that you go and test the default core block patterns with your existing themes, to make sure that everything looks correct.

The pattern and the example code used in this lesson, is available for download on the GitHub repository.

So, how do you create a new block pattern?

The first step is of course to have a plan for what you want your block pattern to do. I am going to take a contact form, provided by Ninja Forms, I am going to add a background image to it,and place a heading above it.

[Screen: A new post is created and opened in the block editor. A cover block is selected in the add bock menu.]

I have installed the plugin that I need, and the first element that I am going to add in the editor is a cover block.

[Screen: An image of a flower drawing is selected in the media library.]

For the cover block, I have selected an image that is already in my media library, that I am going to set as the background.

I want to adjust the colors a little bit so I am going to select a gradient, on top of the background image. I would also like the block to be a little wider.

Now, I will add my heading text, and I am going to make the text a little bit larger,
and move it to the top of the cover block.

[Screen: The heading text size is increased in the block settings sidebar. The heading is moved using the content positioning tool, in the toolbar of the cover block. ]

Next I am adding the Ninja Forms block, and here I have to select which form I would like to show.

[Screen: The Ninja Forms block is selected from the add block menu. The block has a form with a select list, where the plugins contact forms are listed.]

Then I will save the block content, and preview it on the front.

[Screen: The pattern is presented on the front of the website, it has a flower background with a gradient, a centered large heading, and a centered contact form with two text input fields, a text area, and submit button.]

This looks OK, but I still need to make these blocks into a pattern.

[Screen: The screen returns to the block editor]

I am going to copy all of the block code from the code editor mode and then I am going to use this as a value, inside a PHP function called register_block_pattern.

		'title'         => The visible name in the editor,
		'viewportWidth' => The width of the pattern preview (int),
		'categories'    => An array of categories,
		'description'   => A description of the pattern,
		'keywords'      => An array of keywords used in the search,
		'content'       => The block comment and markup,

Official documentation.

[Screen: Code examples are displayed in Visual Studio Code.]

In my theme, I have prepared a new file that I called block-patterns.
But you can also place this inside your functions.php file if you prefer.

Because this is a new feature, I am going to check if the function exists before I do anything else.

I do this with a simple if statement: If function exists, register_block_pattern, do this.

I am also checking for the Ninja Forms plugin, since it is used inside the pattern.

if ( function_exists( 'register_block_pattern' ) ) {
	/** Check if Ninja forms is active. */
	if ( function_exists( 'ninja_forms' ) ) {

The first property inside the register_block_pattern function, is a unique name for the pattern. I am using a prefix, which in my case is my theme slug, and, the slug for the pattern name.


This is followed by an array of properties:

		'title'         => The visible name in the editor,
		'viewportWidth' => The width of the pattern preview (int),
		'categories'    => An array of categories,
		'description'   => A description of the pattern,
		'keywords'      => An array of keywords used in the search,
		'content'       => The block comment and markup,

The required items are:
The title, which is the visible name inside the block editor,
and the content, where we place the block markup.

The function also has four optional properties.
Each pattern comes with its own preview.
The viewportWidth property lets us specify the width of the pattern
inside the preview. This is useful if the pattern is extra tall or narrow.

The description, is a visually hidden text that describes the pattern.
It is a compliment to the visual preview, for users with visual impairment, who may use a screen reader to use the editor.
So even though it says it’s optional, I encourage you to always use it.
In time, as more block patterns are added, it might be difficult to differentiate between block patterns that has very similar titles.

The final two properties helps users find your block pattern
inside the editor: Keywords, and categories.
The values for both these properties needs to be formatted as an array.

You can add any suitable words that you want as your keywords.
Remember to wrap the word inside a translation function.

Block pattern categories

For the categories, you have two options: Either use a category provided by WordPress, or register your own.

The available categories are:

  • Buttons
  • Columns
  • Gallery
  • Header
  • Text

I would like to register two categories: Forms, and example.
This is done with the help of the function register_block_pattern_category.

It uses two properties: The slug, in this case forms, and the visible label:

if ( function_exists( 'register_block_pattern_category' ) ) {
      array( 'label' => __( 'Forms', 'text-domain' ) )

The slug is placed inside the categories property of register_block_pattern. You can register multiple categories separated by a comma.

         	'categories'  => array( 'forms', 'example' ),

The pattern will be visible under both categories in the editor.

If you choose to not add a category, the pattern will be visible under the label Uncategorized.

Now we can move on to the content, and the code that we copied from the code editor mode.

'content'     => '
	<!-- wp:cover {"url":"http://localhost:8888/wp-content/uploads/2020/08/flora.png",
"id":2038,"gradient":"blush-light-purple","contentPosition":"top center","align":"wide"} -->
	<div class="wp-block-cover alignwide has-background-dim has-background-gradient 
has-custom-content-position is-position-top-center"
	<span aria-hidden="true" class="wp-block-cover__gradient-background 
	<div class="wp-block-cover__inner-container">
	<!-- wp:heading {"align":"center","style":{"typography":{"fontSize":60}}} -->
	<h2 class="has-text-align-center" style="font-size:60px">' . __( 'Book an appointment', 'text-domain' ) . '</h2>
	<!-- /wp:heading -->
	<!-- wp:ninja-forms/form {"formID":1,"formName":"Contact Me ( ID: 1 )"} -->
	<div class="wp-block-ninja-forms-form">[ninja_forms id=1]</div>
	<!-- /wp:ninja-forms/form --></div></div>
	<!-- /wp:cover -->

I prefer to wrap my code inside single quotes, if you want to use double quotes,
remember that the double quotes that are inside the HTML code, needs to be escaped with backslash.

This simple pattern only has one custom text string, “Book an appointment”, which is our heading. But we still need to make that translation ready.

We can add the translation function directly in our string:

<!-- wp:heading {"align":"center","style":{"typography":{"fontSize":60}}} -->
<h2 class="has-text-align-center" style="font-size:60px">' . 
__( 'Book an appointment', 'text-domain' ) . '</h2>
<!-- /wp:heading -->

If we need to use more advanced code, or conditional logic, for example to display a message if Ninja Forms is not installed, it would have been better to create a variable, and use that variable as a value inside the content (See the course material for full example).

There is still one more thing that we need to update.
For the cover blocks background image to work, we need to replace localhost, with a path in our theme.

<!-- wp:cover {"url":
"id":2038,"gradient":"blush-light-purple","contentPosition":"top center","align":"wide"} -->

I have placed the flower image inside my themes images folder and the function I have chosen to use to include the image,
is get_theme_file_uri.

<!-- wp:cover {"url":"' .
esc_url( get_theme_file_uri( 'assets/images/flora.png' ) ) . '",
"id":2038,"gradient":"blush-light-purple","contentPosition":"top center","align":"wide"} 

My next and final tip is optional.
If you want to be able to style your pattern, you can add a CSS class to the wrapper element. In this case our cover block.

First we add the className attribute inside the block comment,
where the value is the CSS class.

<!-- wp:cover {"className":"theme-slug-contact-form", ...

And we need to duplicate this for the wrapping div, so we place the class name inside the class attribute:

<div class="wp-block-cover theme-slug-contact-form 

Block pattern code example: