Introduction to block patterns

Level: Beginner, developer

Estimated reading time: 10 minutes

This lesson is an introduction to WordPress block patterns. You will learn how to create patterns, register custom pattern categories, disable them, and add them to block templates using the pattern block.

You can find the code examples and images for the patterns in this lesson in the GitHub repository.

What is a block pattern?

A block pattern is a group of blocks that you combine to create reusable layout elements. Block patterns help users select premade designs that they can customize using an infinite number of color options and media.

You can preview patterns in the new pattern explorer and place them in your content using the block inserter. You can add multiple copies of the same pattern to a post or page and freely edit the blocks.

In the pattern explorer, you can search for patterns provided by the theme, plugins, WordPress core, and featured items from the pattern directory. The editor lists patterns by category:

The block pattern explorer displays larger versions of the pattern compared to the block inserter sidebar.

How do block patterns benefit theme developers and designers?

By combining blocks with custom block styles and block variations, you can style and create patterns with different purposes for your theme. By creating a pattern library, you can create time-saving layouts that look and feel unique with only minor changes.

You can reuse block patterns and place them anywhere in the content or a block theme. Patterns offer more flexibility than a customizer option or an options page because you can style them using built-in editor controls.
Patterns are easier to maintain than code created for the customizer since you don’t need to build your own controls: Text inputs, image uploads, font- and color options are all provided by the block editor.

How to create block patterns

The first step is to have a plan for what you want your block pattern to do. Next, you can start grouping blocks together in the editor and try different styles. You will use the block markup as a value when registering the block pattern.

Registering the block pattern

You register block patterns using a PHP function called register_block_pattern together with an init hook:

function prefix_block_pattern() {
  register_block_pattern( ... );
add_action( 'init', 'prefix_block_pattern' );

WordPress block patterns can only be registered using PHP; it is impossible to register them using JavaScript.

Create a new folder in your theme called patterns.
Next, create a new PHP file that you will use to register the pattern. Use one file per pattern.
I will explain shortly why this is important for future-proofing your patterns.
Remember to include the PHP file from your theme’s functions.php file.

– If your theme supports WordPress versions below WordPress 5.5, you must first check if the
register_block_pattern function exists. Otherwise, you may cause PHP notices.

In my example, I am going to use and style a contact form provided by Ninja Forms, so I am also going to check if the plugin is active:

if ( function_exists( 'register_block_pattern' ) &&
        function_exists( 'ninja_forms' ) ) {
                register_block_pattern( ... );

The first property inside the register_block_pattern function is a unique identifier. The identifier includes a prefix or namespace; the theme slug, followed by a forward slash and a slug for the pattern. Examples:


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,
		'blockTypes'    => An array of blocks. Adding these blocks in the editor will display a preview of the block pattern.
		'inserter'      => false,
		'content'       => The block comment and markup,

The required items are:

  • title, which is the visible name in the block editor
  • content, where you place the block markup.

The function also has six optional properties:

  • Each pattern comes with its own preview. The viewportWidth property lets you 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 impairments, who may use a screen reader to use the editor.
  • Inserter lets you choose if the pattern should be available in the block inserter or not.

By adding an array of blocks to the blockTypes attribute, you can preview and select the pattern directly in the inserter instead of adding the plain block. It is a faster way for your users to place your block patterns:

The pattern inserter can display the block as well as block patterns that use the blockTypes attribute.

The final two properties also help users find your block pattern in the editor: Keywords and categories. You need to format both these properties as an array. You can add any suitable words as your keywords. Remember to wrap the word inside a translation function.

Adding block markup to the pattern

Copy the markup for your patterns from the block editor and paste it into content.
In my example pattern, I am using a cover block with a background image and a gradient, a heading, and the contact form:

'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 to escape the double quotes inside the HTML code with a backslash.

This simple pattern only has one custom text string, “Book an appointment,” and the text needs to be translation-ready. 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 -->

For the cover block’s background image to work, you need to replace “localhost” with a path in the theme. Place the image inside the themes images folder, and include it with 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"} 
Example block pattern using Ninja Forms and a cover block.

How to add a CSS class to a block pattern

You can add a CSS class to the wrapper element to style your pattern. In this case, the cover block.

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

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

You need to duplicate this for the wrapping div. Place the class name inside the class attribute:

<div class="wp-block-cover prefix-contact-form 

Should block patterns contain default content?

It depends. Who is the pattern for, what is it for, and how much content is there? It can be easier for users to get started if you include sample content. It may be easier for them to edit content already in place than add new content.
Local images included in patterns are lost when the user switches themes. Encourage users to add their own media.

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
  • Query

You can register categories with the help of register_block_pattern_category.
The function 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' ) )

You then use the slug 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 not to add a category, the pattern will be visible under the label Uncategorized.

How to remove block patterns

Both block patterns and most block pattern categories can be unregistered.
To remove all WordPress default block patterns, there is a handy trick that will feel familiar to most theme authors:

remove_theme_support( 'core-block-patterns' );

You need to add this code using an init hook or after_setup_theme, and you will most likely place this inside a function together with the rest of your theme support.

To remove a single block pattern, use the PHP function unregister_block_pattern together with the pattern prefix and slug:

unregister_block_pattern( 'prefix/my-awesome-pattern' );

If you want to remove a pattern that is included in WordPress, core, use core as the prefix:

unregister_block_pattern( 'core/two-buttons' );

This also works for block patterns created by plugins; all you need is the prefix and name of the pattern.

How to hide block patterns from the pattern directory

You can prevent loading patterns from the pattern directory with a filter called should_load_remote_block_patterns. Example:

add_filter( 'should_load_remote_block_patterns', '__return_false' );

Removing block pattern categories

To remove a category, use the function unregister_block_pattern_category together with an init hook.

function prefix_unregister_category() {
	unregister_block_pattern_category( 'buttons');
add_action( 'init', 'prefix_unregister_category' );

The uncategorized block pattern category is used as a fallback when a pattern does not have a category, and it can not be unregistered with this function.

How to use the pattern block to place block patterns in templates

Earlier I mentioned the inserter attribute in register_block_pattern and how you can use it to hide the pattern. This method is useful when you need to use PHP strings and translations in your block templates and template parts. You add your PHP code as part of a block pattern and then include that pattern in the template. Users can not preview or insert the pattern, but they can still edit the blocks in the editor.

The markup for the pattern block is:

<!-- wp:pattern {"slug":"prefix/pattern-slug"} /-->

Troubleshooting block patterns

I have run into the problem where my pattern markup is invalid countless times. Many times, the message that is shown when I try to resolve a block markup error is not helpful at all.

What I try to do to solve markup problems is:

  • First, double-check that I have copied all the tags correctly and that there are no missing closing tags.
  • Adjust the spacing between the block patterns in the HTML code; try removing extra empty lines.
  • Remove blocks from the pattern one at a time to try to identify where the problem is.

Finally, re-create the pattern in the editor, copy all the code again and hope for the best! 🙂

Future changes

Admittedly, this is a little speculative because there is a proposal to change how we register block patterns, but it has not been implemented yet.
The proposal is to place the markup for the block pattern in a PHP or HTML file inside a theme folder called patterns. WordPress would then register the patterns for you automatically.
That is why I want to recommend you to start using the patterns folder and to use one file per pattern.


WordPress training has an introduction video for finding and using block patterns. You can share this with your users so that they can get familiar with how to work with the patterns you have included in your theme or plugin.