What Are They and How to Use Them

This guide will explore everything you need to know about block patterns, including how to make, register, and use them. Let’s get started!

An overview of WordPress block patterns (and why you might consider using them)

A WordPress block pattern is a sequence of blocks grouped into a single template. Block patterns were first introduced in WordPress 5.5 (Eckstine), and they span different categories, including buttons, columns, and text.

You can find these elements within the WordPress Block Pattern Directory:

WordPress block patterns might sound similar to reusable blocks. However, they serve very different purposes:

• Block patterns are kind of like a jumping-off point for your design. You import the block pattern as the base, and then you customize all the content for each design. You could use the same block pattern in two different posts, but there’s nothing linking them together.
• Reusable blocks show the exact same content in every instance of that block. For example, maybe you want to add a consistent CTA at the end of your blog posts. You would do that with a reusable block. If you ever updated that reusable block in the future, the update would apply to all instances of that reusable block.

When you use WordPress block patterns, you can speed up your page design process. Rather than dragging and dropping different blocks onto the page, you can choose from pre-made layouts.

? Block patterns can also be handy from a development viewpoint. If you’re creating different WordPress themes, these templates can speed things up. Plus, you can even make and register your own block patterns to fit your specific needs.

How to use WordPress block patterns (three methods)

It’s easy to find, insert, and edit block patterns. Let’s look at three different methods! ?

1. Copy and paste patterns from the Block Patterns Directory
2. Insert patterns directly from the Block Editor
3. Submit block patterns

1. Copy and paste patterns from the Block Patterns Directory

First, you can copy and paste block patterns directly from the WordPress directory. This method allows you to browse multiple layouts and see their previews for inspiration.

Start by heading to the Block Pattern Directory. Then, click on a pattern and select Copy Pattern under its name:

Alternatively, you can click on Add to favorites to save the pattern in your collection. However, you’ll need to be signed in to your WordPress.org account.

Next, navigate to your WordPress post or page and paste in the block pattern:

Now you can edit the individual blocks or the entire pattern to fit your needs.

2. Insert patterns directly from the Block Editor

You can also add block patterns directly from the Block Editor. This method is quicker because you won’t have to navigate back and forth from the Block Pattern Directory. However, the previews will be smaller and more difficult to view.

Open up a post or page and click on the + icon in the top-left corner. Select Patterns, and you’ll see a list of the available templates:

Click on the layout of your choice, and it will immediately be added to your post or page. You can also use the drop-down menu to search for block patterns by category.

3. Submit block patterns

You may have already noticed that many of the block patterns in the official directory are user-submitted. You can contribute by making your own pattern and submitting it.

You’ll first need to be logged in to your WordPress.org account. Next, head to the New Pattern page and arrange your blocks into a unique layout:

Make sure that your pattern complies with WordPress’ requirements. Then, click on Submit. You’ll now be prompted to enter a title and description for your pattern:

Finally, select relevant categories for your block pattern and click on Finish. Your layout will now be submitted for review.

How to create and register new block patterns (for theme and plugin development)

This section will explain how you can create and register your own block patterns for design and development purposes. Let’s take a look! ?

Step 1: Register your block pattern

First, you’ll need to make your block pattern by organizing different blocks on a page. Once you’re happy with the design, it’s time to use the register_block_pattern PHP function with an init hook.

It will look like this in its basic form:

function prefix_block_pattern() {
  register_block_pattern( ... );
}
 
add_action( 'init', 'prefix_block_pattern' );
Code language: JavaScript (javascript)

Now, make a new folder in your theme and call it “patterns.php.” We also recommend making an additional PHP file to register your new pattern. It will need the PHP from your functions.php file to work correctly.

Your new block pattern will need the following properties:

• title: The block pattern’s name.
• content: The container for the block’s markup.

You can also add these properties:

• description: A hidden description of your block pattern visible on screen readers and similar devices.
• categories: The category for your block pattern (we’ll discuss this more later).
• keywords: Key phrases to help users find your block pattern.
• viewportWidth: The width of your pattern.
• blockTypes: A description of the ideal block types for this pattern.
• inserter: Use “false” to make the block pattern invisible in the inserter.

Your block pattern registration should look something like this:

register_block_pattern(
	'new-theme/amazing-block-pattern',
	array(
		'title'         => 'Amazing Block Pattern',
		'viewportWidth' => 'The pattern preview's width',
		'categories'    => 'Your block pattern's categories',
		'description'   => 'An amazing block pattern description', 
		'keywords'      => 'Your block pattern's keywords',
		'blockTypes'    => 'An array of blocks',
		'content'       => 'The block comment and markup',
	)
);
Code language: PHP (php)

You’ll also need to add your block pattern markup. We’ll explain this in the next step.

Step 2: Add block markup and CSS markup

Head back to the collection of blocks you put together on a WordPress page. You’ll need to copy their markup (code) from the Block Editor. In our example, we’re using the markup of a block pattern with a background image, title, columns, and text.

Our example block pattern looks like this:

Copy the markup and paste it on the content line, wrapped in single quotation marks:

'content' => '

<div class="wp-block-cover alignfull" style="min-height:800px"><span aria-hidden="true" class="has-background-dim-60 wp-block-cover__gradient-background has-background-dim"></span><img class="wp-block-cover__image-background" alt="forest" src="https://s.w.org/images/core/5.8/forest.jpg" data-object-fit="cover"/><div class="wp-block-cover__inner-container">
<h2 class="alignwide has-text-color" style="color:#ffe074;font-size:64px">Forest.</h2>



<div class="wp-block-columns alignwide">
<div class="wp-block-column" style="flex-basis:55%">
<div style="height:330px" aria-hidden="true" class="wp-block-spacer"></div>



<p class="has-text-color" style="color:#ffe074;font-size:12px;line-height:1.3"><em>Even a child knows how valuable the forest is.</em></p>
</div>



<div class="wp-block-column"></div>
</div>
</div></div>

',
Code language: HTML, XML (xml)

If your block pattern contains an image, you’ll also need to make that graphic accessible. First, add the picture to the images folder within your theme folder. Then, use a get_theme_file_uri.

You can also add CSS classes to your block pattern with the className attribute within the wrapper element. In our example, that’s the cover block.

Therefore, your CSS will look something like this:

<!-- wp:cover {"className":"amazing-block-pattern", ...
Code language: JavaScript (javascript)

Remember to replace “className” with your CSS class. You’ll also need to add this code to the wrapping div, with the class name included:

<div class="wp-block-cover prefix-amazing-block-pattern
Code language: JavaScript (javascript)

Step 3: Choose or make a new block pattern category

Before, we briefly discussed the categories element. You’ll need to choose one of WordPress’ block pattern categories or design your own.

WordPress currently has these categories:

• Gallery
• Columns
• Buttons
• Text
• Header
• Query

If you’d like to use a new block pattern category, you’ll need to use the register_block_pattern_category helper function. It includes both the name of your new category and the label of your block pattern:

if ( function_exists( 'register_block_pattern_category' ) ) {
    register_block_pattern_category(
      'custom',
      array( 'label' => __( 'Custom', 'text-domain' ) )
   );
}
Code language: PHP (php)

Once it’s registered, you can add this category to the categories line for your block pattern.

How to remove and hide block patterns

If you want to remove your custom block pattern, you can use the unregister_block_pattern function with your layout’s prefix and slug. You’ll also need to use the init hook. It should look something like this:

unregister_block_pattern( 'prefix/amazing-block-pattern' );
Code language: JavaScript (javascript)

You can also hide all block patterns from the Block Pattern Directory. This method could be helpful if you don’t want to enable these templates within your new theme.

You’ll just need to use the should_load_remote_block_patterns filter, which will look like this:

add_filter( 'should_load_remote_block_patterns', '__return_false' );
Code language: JavaScript (javascript)

? We recommend consulting WordPress’ Developer Resources if you need any more guidance. There, you’ll find detailed documentation for all kinds of block pattern development.

How to create WordPress block patterns without code

If you don’t want to go the code route for creating block patterns, you can also install a plugin like BlockMeister.

BlockMeister lets you build block patterns from within the editor. Once you install the plugin, you can select one or more blocks and then save them as a block pattern, much like you do reusable blocks.

You’ll also get an in-dashboard interface to manage all of your block patterns and organize them with categories.

Conclusion ?

WordPress block patterns are collections of individual blocks that form cohesive templates. You can use them to design your posts and pages more quickly. Plus, they’re easy to customize, and you can even create and submit your own layouts.

Do you have any questions about WordPress block patterns? Let us know in the comments section below!