Full Site Editing

This lesson is an introduction to WordPress block patterns, including synced patterns, formerly reusable blocks. You will learn how to create patterns via the user interface, the patterns folder, or a PHP function called register_block_pattern(). The lesson describes how to register pattern categories, use patterns from the pattern directory, and disable patterns.

This is a developer-oriented lesson and I will not go into details on how to assemble the blocks in the editor to create your ideal design.

Estimated reading time: 24 minutes

What is a block pattern?

A block pattern is a group of blocks that you combine to create reusable layout elements and page sections. Technically, patterns use the markup of individual blocks. This markup includes the HTML comment with the block attributes and the block content itself, such as text and links to images.

Block patterns help you select pre-made designs that you can customize using infinite color options and media. They help you speed up your template and page creation, and they can be as small as a single block or as large as a full-page layout. You can add patterns to your content using the block inserter. They can also be part of a template, template part, or even nested inside other patterns.

WordPress includes default patterns and pattern categories. Themes and plugins can add custom patterns, and you can find more user-contributed patterns in the WordPress.org pattern directory.

From WordPress version 6.3, you can create patterns directly in the editor. This new feature is available for classic themes and block themes, as I will show later in this lesson.

How do theme developers and designers benefit from block patterns?

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

Designers can assemble their block patterns directly in the WordPress editor and export the code to a developer. Developers have several ways to register block patterns and can also decide if the pattern should be available to users.

What is a synced pattern?

From a user perspective, the most significant difference between a standard, non-synced pattern, and a synced pattern is what happens after you have placed it in the content:

• If you place a non-synced pattern and need to make changes afterward, your changes are not synced across the site. So, if you want the changes to be applied everywhere, you need to remember where you used the pattern and repeat the same change on every page or post where you used it.
• If you place a synced pattern and need to make changes afterward, the changes are applied everywhere. You can edit a synced pattern from the new pattern management screen or by selecting a pattern you have placed in the editor.

Once you have placed a standard pattern, the blocks are like any other blocks in your content. You can’t tell that the blocks used to be a block pattern. There is no built-in way to identify these blocks as a pattern, and theme- and plugin authors have tried different ways to work around it.

A synced pattern behaves like one unit. Like a pattern block with nested inner blocks. It stays grouped and is labeled with the pattern name. It also has a different color, which makes it easier to find in the editor. In this example from WordPress 6.3, the pattern is called “testing”:

And this is what a synced pattern looks like in the List View, with the blocks nested inside:

Patterns can be created with or without using the database

To change to a developer perspective, I want to move away from “synced “and “not synced” for a moment, and instead distinguish whether the pattern is stored in the database using the wp_block post type.

In short, before version 6.3, WordPress made patterns available through a block pattern registry class and private functions. Plugins and themes registered the pattern, and the markup of the blocks was provided through a PHP function or in a file in the theme’s patterns folder.

From WordPress 6.3, users can create patterns directly in their WordPress installation. These patterns are site-specific, and WordPress needs to store them in the database. To make this possible, the post type used for reusable blocks; wp_block, was re-purposed for patterns. Not only for synced patterns but all user-created patterns.

Patterns that are not created using the wp_block post type can not be synced. Parts of this lesson that apply to this type of pattern have a notice at the top.

Patterns that use the ‘wp_block’ post type

Patterns registered with the wp_block post type works similarly to other WordPress post types. They can be managed with code using a plugin but are primarily managed through the WordPress interface. They can be either synced or not synced. The sync status is saved to a post meta called wp_pattern_sync_status.

Where a standard pattern places the markup of the individual blocks into the editor, synced patterns use a reference to a post ID:

<!-- wp:block {"ref":1874} /-->

In this fictive database, the post with ID 1874 is of the post type wp_block, and contains the markup of the blocks in the post_content field.

Creating patterns in the block editor

Now, let’s jump into how to create this new type of pattern block. Starting in WordPress 6.3, creating a new pattern for your site is as easy as selecting the block, opening the options menu in the toolbar, and selecting “Create pattern”.

The screenshots below are from WordPress 6.3.1, and the interface may change in future WordPress versions:

In the next step, you enter a name for the pattern and decide if it should be synced or not.
Starting in WordPress 6.4, you can also add a block pattern category:

When you save your content and reload the editor, WordPress transforms your blocks into a pattern block:

The example shows a pattern with a single paragraph, but you will often want to use more than one block. When you have multiple blocks in your pattern, you want to place them inside a “container block” like a group or row, and then use the “Create pattern” option on this outer block. This way all your blocks will stay together.

Classic themes: Creating and managing patterns in the WordPress admin

To open the pattern management screen, select a synced pattern in the editor, open the options menu in the block toolbar, and select “Manage patterns”.

• If you use a classic theme or are logged in as a user who does not have permission to use the Site Editor, this opens the admin page that was previously used for reusable blocks.
• If you are using a full site editing theme, you are redirected to the Site Editor (Read more about managing patterns in the Site Editor below).

Other than the option in the toolbar menu, there is no easy way to access the admin page. The direct link to the page is example.com/wp-admin/edit.php?post_type=wp_block where example.com is replaced with your website URL.

Your patterns are listed in a table similar to posts or pages. You can add new patterns, search for patterns, edit, and trash patterns.

Selecting “Add New” takes you to the block editor, where you can place and style all the blocks you want to use in your pattern. You can save your patterns as drafts or publish them right away. Starting in WordPress 6.4, you will also be able to add categories.

Block themes: Creating and managing patterns using the Site Editor

WordPress 6.3 added a new interface for patterns in the Site Editor. This interface is only available for block themes. Go to Appearance > Editor > Patterns to open the new patterns list.

You can choose between different pattern categories in the Site Editor sidebar. The sidebar lists all user-created patterns under the heading “My patterns”.

On the right side of the screen, you can choose if you want to view all patterns, synced patterns, or standard patterns. Each pattern has a preview and an action menu (the three dots menu):

You can create a new pattern by selecting the plus icon at the top of the Site Editor sidebar.
This opens the same modal that WordPress uses to create patterns in the block editor. You can add a name and category and select the sync status. The form requires adding a name.

What happens when you delete a user-created pattern?

If you have placed a user-created pattern in your content and then trash it or set it as a draft, the pattern will stop showing on the front.

WordPress does not remove the pattern from your content, and the pattern will continue to show in the block editor. If you delete the trashed item, the pattern will show an error message in the editor:

(If you are using the Site Editor, the trash and delete flow can be confusing, but there are plans to improve this in WordPress 6.4.)

How to export and import block patterns

Users can export and import patterns as JSON files. This is useful if you have created a pattern on one site and want to use it on a different site. There are plans to add this feature to the Site Editor in WordPress 6.4. Until then, you can use the classic pattern management screen.

Open the pattern management screen. Focus on or hover over the pattern you want to export. Select “Export as JSON”.

This will download a file called patternname.JSON. Example file:

__file	"wp_block"
title	"testing"
content	"<!-- wp:paragraph -->\n<p>This is only a test pattern with a paragraph.</p>\n<!-- /wp:paragraph -->"
syncStatus	""

To import a pattern, select the button “Import from JSON” and choose your pattern JSON file:

When you select the “Import” button, you will receive a notification confirming that the import was successful. Refresh the page to see your new pattern in the pattern list.

The Pattern Explorer

You can find a feature called the Pattern Explorer in the block editor. Click on the block inserter in the top left of the editor, select the Patterns tab, and the button “Explore all Patterns”.
In Pattern Explorer, you can search for patterns provided by the theme, plugins, WordPress core, and featured items from the WordPress.org pattern directory.

I want to mention the pattern explorer because it is important to know that it is not possible to edit, create, or delete block patterns from this screen.

Registering block patterns

Plugins and themes can add patterns using the PHP function register_block_pattern() together with an init hook. Themes can also register patterns by placing PHP files inside a folder called patterns. WordPress searches the folder and parses the file headers to finally pass the data to register_block_pattern().

Using the register_block_pattern() function directly may look like this:

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

While using a file inside the theme patterns folder may look like this:

<?php
/**
 * Title: The visible name in the editor,
 * Slug: prefix/contact-form,
 */
?>
The block markup

In this section, I will describe both methods in detail, with code examples and use cases. As you can see from the example, you do not need to know much PHP to use the patterns folder.
I recommend using the patterns folder when registering theme patterns, because of its simplicity. Note that there is no way to register block patterns using JavaScript.

Parameters

The parameters used with the PHP function and the patterns folder are the same, but the formatting and type are different. This can be confusing, but to avoid too much repetition, I have added a comparison table to describe the differences.

• The PHP function uses arrays, but in the file, you use items separated by a comma.
• Parameter names that use camelCase in the PHP function use a space in the file:
  blockTypes become Block Types.

Required parameters

Optional parameters

Also see:

• How to display the pattern selection when creating a new page
• How to display the pattern selection when creating a new template
• How to hide a pattern from the block inserter

Example: How to use register_block_pattern()

First, lets look at the oldest method of creating block patterns, added in WordPress version 5.5.
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' );

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

Being able to register patterns conditionally is one use case for using the PHP function instead of the patterns folder.

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!

How to add block markup to the pattern

Copy the markup for your patterns from the block editor: Select the outer block in your pattern, go to the block toolbar, and select “Copy”.
Next, paste the markup as a value for the content parameter.

In my example pattern, I am using a cover block with a background image and a gradient, a heading block (in blue), and the contact form (in pink):

'content'     => '<!-- wp:cover {"url":"http://localhost:8888/wp-content/uploads/2020/08/flora.png",
"id":2038,"dimRatio":50,"gradient":"blush-light-purple","contentPosition":"top center","isDark":false,"align":"wide"} -->
<div class="wp-block-cover alignwide is-light has-custom-content-position is-position-top-center"><span aria-hidden="true" class="wp-block-cover__background has-background-dim wp-block-cover__gradient-background has-background-gradient has-blush-light-purple-gradient-background"></span>
<img class="wp-block-cover__image-background wp-image-2038" alt="" src="http://localhost:8888/wp-content/uploads/2020/08/flora.png" data-object-fit="cover"/><div class="wp-block-cover__inner-container">
<!-- wp:heading {"textAlign":"center","style":{"typography":{"fontSize":60}}} -->
<h2 class="wp-block-heading 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 has a custom text string, “Book an appointment,” and the text needs to be translation-ready. Add the translation function to the string:

<!-- wp:heading {"align":"center","style":{"typography":{"fontSize":60}}} -->
<h2 class="wp-block-heading 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_template_directory_uri():

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

Example: How to register block patterns using the theme patterns folder

Themes (but not plugins) can register patterns by adding PHP files with a specific file header to a folder named patterns. WordPress searches this folder for patterns and makes them available in the editors according to the parameters in the file header.

Create a new folder called patterns in the root of your theme folder.
Create a single PHP file for each pattern you want to add and place them in the patterns folder. WordPress only supports creating patterns with PHP files; you cannot use HTML or JSON files to create patterns in this folder.

You must add all properties in a comment inside the file header except for the content, which you place in the main part of the file. The only required properties are title and slug. If you forget one of them, you will see a PHP notice.

WordPress will throw notices if it finds errors in the file header but will not check beforehand if your pattern markup in the content is valid.

Pattern file examples

Filename: footer-links.php

<?php
/**
 * Title: Footer links -The visible name in the pattern inserter
 * Slug: theme-slug/footer-links
 * Categories: text, site-footer 
 * Description: A description of the pattern
 * Keywords: footer, links, copyright, keywords used in the search
 * Block Types: core/navigation, core/site-title, core/social-links
 */
?>

After closing the comment, you can add the block markup as plain text. Or, you can combine the markup with PHP.

A difference between adding PHP in the block pattern file and adding it in the content of register_block_pattern() is that in the pattern file, you must use echo:

<?php
/**
 * Title: Footer links -The visible name in the pattern inserter
 * Slug: theme-slug/footer-links
 * Categories: text, site-footer 
 * Description: A description of the pattern
 * Keywords: footer, links, copyright, keywords used in the search
 * Block Types: core/navigation, core/site-title, core/social-links
 */
?>

<!-- wp:group {"layout":{"type":"flex","allowOrientation":false,"justifyContent":"space-between"}} -->
<div class="wp-block-group"><!-- wp:group {"layout":{"type":"flex","allowOrientation":false}} -->
<div class="wp-block-group"><!-- wp:paragraph {"fontSize":"extra-small"} -->
<p class="has-extra-small-font-size">
<?php echo esc_html__( 'Copyright', 'text-domain' ) . ' ' . date_i18n( _x( 'Y', 'copyright date format', 'text-domain' ) ); ?></p><!-- /wp:paragraph -->
<!-- wp:site-title {"level":0, "fontSize":"extra-small"} /-->
<!-- wp:social-links {"className":"is-style-logos-only"} -->
<ul class="wp-block-social-links has-icon-color is-style-logos-only"><!-- wp:social-link {"url":"https://wordpress.org","service":"wordpress"} /--></ul>
<!-- /wp:social-links -->
</div><!-- /wp:group -->
</div><!-- /wp:group -->

You can also add additional file header data without breaking the parser:

<?php
/**
 * Title: Footer links -The visible name in the pattern inserter
 * Slug: theme-slug/footer-links
 * Categories: text, site-footer 
 * Description: A description of the pattern
 * Keywords: footer, links, copyright, keywords used in the search
 * Block Types: core/navigation, core/site-title, core/social-links
 *
 * @package theme-slug
 * @since 1.0.0
 */
?>

Block pattern categories

Now that you know how to create patterns, let’s look at how to add custom pattern categories. For categories, you have two options: Either use a category provided by WordPress or register your own.

A common feature is for themes to list their patterns under a category that includes the theme name. This can help users recognize patterns that are designed for the active theme.

The available categories are:

You can register categories with the help of register_block_pattern_category.
The function uses three properties:

• slug: The unique identifier (in the example below, the slug is “forms” with a custom prefix).
• label: The visible name in the editor.
• description: The category description, new in WordPress 6.2

if ( function_exists( 'register_block_pattern_category' ) ) {
    register_block_pattern_category(
      'prefix_forms',
      array(
            'label' => __( 'Forms', 'text-domain' ),
            'description' => __( 'Forms for comments and more', 'text-domain' ),
       )
   );
}

You then use the slug inside the categories property of your pattern. You can register multiple categories separated by a comma:

register_block_pattern(
	'prefix/pattern-slug',
	array(
         	'categories'  => array( 'prefix_forms', 'prefix_example' ),
        ...
        )
);

The pattern will be visible under both categories in the editor. If you choose not to add a category, WordPress will show the pattern under the label “Uncategorized”.

User-created block pattern categories

As I described above in Creating patterns in the block editor, users can categorize their custom patterns. The block pattern category is a custom taxonomy on the wp_block post type, called wp_pattern_category. This means that theme and plugin developers can also use the taxonomy if they prefer.
Note that this taxonomy is not public, because it is only intended for use in the WordPress admin, not the front-end.

How to add a CSS class to a block pattern

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.

Using code:
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 

Using the interface (for user-created patterns):

User-created patterns do not have a default wrapper to which you can add a class. Instead, you need to add a wrapper manually. Add a group inside the pattern block, and place all the remaining blocks inside this group.
Next, select the group, open the Advanced panel in the block settings sidebar, and set an additional CSS class.

How to remove block patterns

Block patterns and most of the 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 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:

unregister_block_pattern( 'core/two-buttons' );

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

How to prevent loading block patterns from the pattern directory

You can prevent loading patterns from the WordPress.org 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' );

How to place patterns in block templates

If you are using a block theme, you can load patterns in templates, template parts, and other patterns with wp:pattern. In this markup example, the slug is the same parameter and value used to register the pattern:

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

You can only use the prefix and slug combination to reference patterns added by themes or plugins. It does not work with user-created patterns because they can only be referenced by their post ID.

– If the template you are creating is specific to one site and not for a theme that is distributed to many sites, you can find the post ID for the pattern and reference it using wp:block instead of wp:pattern:

<!-- wp:block {"ref":77} /-->

How to include a pattern from the pattern directory

To use a pattern from the WordPress pattern directory in your block theme, you first need to add the pattern to theme.json.

At the root level of theme.json, add a new section called patterns. Then, add an array of pattern slugs. – The pattern slug is the same as the path to the pattern in the directory. If the pattern is located at https://wordpress.org/patterns/pattern/paragraph-heading/, then the slug is “paragraph-heading”. Example:

"patterns": [ "paragraph-heading" ]

I showed you earlier that to include a pattern registered by a theme or plugin in a block template, you need to include the prefix. But this is not needed for patterns that are in the directory. It is enough to use the pattern slug:

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

How to display the pattern selection when creating a new page

Theme developers can present a modal with recommended patterns when a user creates a new page. The modal is opened when the user enters the block editor:

This is useful if you have premade designs that work well on many types of pages since the modal will show on all new pages. To show the pattern selection, add the post content block to the block types parameter of your pattern file:

Block Types: core/post-content

Or, if you are using the register_block_pattern function:

'blockTypes' => array( 'core/post-content' ),

How to display the pattern selection when creating a new template

Similar to when creating pages, you can offer pattern suggestions when users create new templates in the Site Editor. You do this with the help of the templateTypes parameter mentioned above.

When using a file:

Template Types: post, page

When using the register_block_pattern function:

'templateTypes' => array( 'post', 'page' ),

How to hide a block pattern from the inserter

You can use the inserter parameter to hide block patterns from the inserter, in case you only want to use them inside the HTML templates or templates or template parts. This is for the convenience of the developer to help us avoid repeating code. The user will never know that a pattern was used in the template.

When using a file:

Inserter: no

When using the register_block_pattern function, you need to use the boolean false instead of “no”:

'inserter' => false,

How to use a template part inside a block pattern

There is a known issue where the template part cannot be found in the editor if you include a template part in a block pattern. To solve this, the call to the template part needs to include both the template slug parameter and the theme parameter:

<!-- wp:template-part {"slug":"sidebar","theme":"theme-slug"} /-->

Read more about including template parts.

Also, remember that patterns with template parts will not work in the block editor, they are limited to the Site Editor.

How to use the source parameter to indicate if a pattern is from a theme or plugin

So far, I have excluded the optional parameter called source. Source is used internally to allow filtering block patterns depending on if they are from WordPress core, a theme, or a plugin. Normally, you would not use this parameter in a theme, but you may use it in a plugin to ensure the pattern is not considered a “theme pattern”.

– With the changes to the Site Editor interface, this parameter has become less relevant because visually, patterns are no longer listed as being provided by themes or plugins; instead, the description is “Patterns from all sources”.

Link to the pull request that introduced the parameter.

Troubleshooting block patterns

I have run into a problem where my pattern markup is invalid countless times. Most of the time, the message the editor shows when I try to resolve a block markup error is not helpful.

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 identify where the problem is.

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

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 to edit content than add new content. Local images included in patterns are lost when the user switches themes. Encourage users to add their own media.

Resources

The WordPress.org pattern directory

The WordPress training team has an introduction video about finding and using block patterns. You can share this with your users to help them become familiar with patterns: https://learn.wordpress.org/workshop/intro-to-block-patterns/