Managing Block Patterns

A block pattern is a group of blocks combined to create reusable layout elements and page sections. Patterns allow users to add pre-designed, customizable elements to their content with a visual preview of the pattern. They help speed up template and page creation, and can be as small as a single block or as large as a full-page layout. Learn more in the Handbook.

Core Patterns

Core patterns are included from two locations:

Some patterns are stored in the WordPress codebase and included with each version of WP. @todo – what are these?
Other core patterns are fetched remotely from the WordPress Pattern Directory. These patterns have proven to have issues working correctly in older versions of WP. It seems that the patterns in the Directory are not versioned to specific versions of WP.

Creating Custom Block Patterns

Patterns are available through a block pattern registry class (WP 5.5+) and private functions (WP 6+). Plugins and themes register the pattern, and the markup of the blocks is provided through a PHP function or in a file in the theme’s patterns folder. Using the _register_theme_block_patterns function as a template, we’ll set up an init action doing the same thing (with a bail-out whenever we get to WP 6).

How to create a pattern and add it to a theme or plugin

In themes, there is pattern folder where designers/devs can add new pattern_name.php file that will be automatically ingested using the _register_theme_block_patterns function.

Patterns are available through a block pattern registry class and private functions.

Plugins and themes register the pattern, and the markup of the blocks is provided through a PHP function or in a file in the theme’s patterns folder.

Example Block Pattern

<?php
/**
 * Title: BU Test Pattern
 * Slug: responsive-child-starter-3x-block-editor/bu-test-pattern
 * Categories: BU
 * Inserter: yes
 */

?>

<!-- wp:media-text {"align":"full","mediaType":"image","verticalAlignment":"center"} -->
<div class="wp-block-media-text alignfull is-stacked-on-mobile is-vertically-aligned-center"><figure class="wp-block-media-text__media"><img src="https://s.w.org/images/core/5.8/architecture-04.jpg" alt="Close-up, abstract view of architecture." /></figure><div class="wp-block-media-text__content"><!-- wp:heading {"textAlign":"center","level":3,"style":{"color":{"text":"#000000"}}} -->
<h3 class="wp-block-heading has-text-align-center has-text-color" style="color:#000000"><strong>Open Spaces</strong></h3>
<!-- /wp:heading -->

<!-- wp:paragraph {"align":"center","fontSize":"extra-small"} -->
<p class="has-text-align-center has-extra-small-font-size"><a href="#">See case study ↗</a></p>
<!-- /wp:paragraph --></div></div>
<!-- /wp:media-text -->

How to use `register_block_pattern()`

Being able to register patterns conditionally is one use case for using the PHP function instead of the patterns folder. To add patterns in a theme or plugin, you can register standard (unsynced) block patterns using the PHP function register_block_pattern() together with an init hook:

In functions.php:

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

In my example, I am going to use and style a contact form provided by Ninja Forms, so first, I am going to check if this 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 the unique identifier. The identifier includes a prefix or namespace (the theme slug), followed by a forward slash and a slug for the pattern. Examples:

register_block_pattern(
	'prefix/pattern-slug',
         ...

As in:

register_block_pattern(
	'twentytwentytwo/contact-form',
         ...

The identifier is followed by an array of properties, as I described earlier:

register_block_pattern(
	'prefix/contact-form',
	array(
		'title'      => The visible name in the editor,
		'categories' => An array of categories,
		'content'    => The block markup,
	)
);

Remember to wrap the title, keywords and description inside translation functions!

Disabling Block Patterns

Block patterns and most of the block pattern categories can be unregistered. The reasoning behind this is we don’t want to be on the hook for supporting all the core patterns (especially ones utilizing group and column blocks) in case they break or the markup changes in upgrades. This will allow us to create our own using our BU-specific, supported blocks to offer clients similar flexibility.

This will remove and disable core block patterns including those remotely fetched.

add_action( 'after_setup_theme', 'themeslug_remove_core_patterns' );

function themeslug_remove_core_patterns() {
	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 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 single pattern that is included in WordPress, core, use core as the prefix. This also works for block patterns created by plugins; all you need is the pattern’s name and prefix.

unregister_block_pattern( 'core/two-buttons' );

There is a filter to remove just remotely fetched block patterns and keep the core patterns included in the WP core codebase:

add_filter( 'should_load_remote_block_patterns', '__return_false' );

Adding custom styles to a pattern in the editor & frontend

Add CSS classes to patterns

Custom CSS styled block patterns should only be used for patterns registered in a custom theme and not plugins.

We can add CSS classes to block patterns to allow us to style the pattern, without giving full control of the styles to clients.

Per FullSiteEditing, you can add a CSS class to the wrapper element and use that selector to style your pattern.

In the example, I am using the cover block as the wrapper.

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