Block patterns, also frequently referred to as sections, were introduced in WordPress 5.5 to allow users to build and share predefined block layouts in the pattern directory. The directory is the home of a wide range of curated patterns designed by the WordPress community. These patterns are available in simple copy and paste format, require no coding knowledge and thus are a big time saver for users.
Despite many articles on patterns, there is a lack of comprehensive and up-to-date articles on pattern creation covering the latest enhanced features. This article aims to fill the gap with a focus on the recent enhanced features like creating patterns without registration and offer an up-to-date step-by-step guide to create and use them in block themes for novices and experienced authors.
Since the launch of WordPress 5.9 and the Twenty Twenty-Two (TT2) default theme, the use of block patterns in block themes has proliferated. I have been a big fan of block patterns and have created and used them in my block themes.
The new WordPress 6.0 offers three major patterns feature enhancements to authors:
In an introductory Exploring WordPress 6.0 video, Automattic product liaison Ann McCathy highlights some newly enhanced patterns features (starting at 15:00) and discusses future patterns enhancement plans — which include patterns as sectioning elements, providing options to pick pattern on page creation, integrating pattern directory search, and more.
The article assumes that readers have basic knowledge of WordPress full site editing (FSE) interface and block themes. The Block Editor Handbook and Full Site Editing website provide the most up-to-date tutorial guides to learn all FSE features, including block themes and patterns discussed in this article.
Section 1: Evolving approaches to creating block patterns
The initial approach to creating block patterns required the use of block pattern API either as a custom plugin or directly registered in the
functions.php file to bundle with a block theme. The newly launched WordPress 6.0 introduced several new and enhanced features working with patterns and themes, including pattern registration via a
/patterns folder and a page creation pattern modal.
For background, let’s first briefly overview how the pattern registration workflow evolved from using the register pattern API to directly loading without registration.
Use case example 1: Twenty Twenty-One
The default Twenty Twenty-One theme (TT1) and TT1 Blocks theme (a sibling of TT1) showcase how block patterns can be registered in the theme’s
functions.php. In the TT1 Blocks experimental-theme, this single block-pattern.php file containing eight block patterns is added to the
functions.php as an
include as shown here.
A custom block pattern needs to be registered using the
register_block_pattern function, which receives two arguments —
title (name of the patterns) and
properties (an array describing properties of the pattern).
Here is an example of registering a simple “Hello World” paragraph pattern from this Theme Shaper article:
After registration, the
register_block_pattern() function should be called from a handler attached to the
init hook as described here.
Once block patterns are registered they are visible in the block editor. More detailed documentation is found in this Block Pattern Registration.
Block pattern properties
The following is an example of a quote pattern plugin code snippets taken from the WordPress blog.
Using patterns in a template file
Once patterns are created, they can be used in a theme template file with the following block markup:
An example from this GitHub repository shows the use of “
footer-with-background” pattern slug with “
tt2gopher” prefix in TT2 Gopher blocks theme.
Early adopters of block themes and Gutenberg plugin took advantage of patterns in classic themes as well. The default Twenty Twenty and my favorite Eksell themes (a demo site here) are good examples that showcase how pattern features can be added to classic themes.
Use case example 2: Twenty Twenty-Two
If a theme includes only a few patterns, the development and maintenance are fairly manageable. However, if a block theme includes many patterns, like in TT2 theme, then the
pattern.php file becomes very large and hard to read. The default TT2 theme, which bundles more than 60 patterns, showcases a refactored pattern registration workflow structure that is easier to read and maintain.
Taking examples from the TT2 theme, let’s briefly discuss how this simplified workflow works.
2.1: Registering Patterns Categories
For demonstration purposes, I created a TT2 child theme and set it up on my local test site with some dummy content. Following TT2, I registered
footer-with-background and added to the following pattern categories array list in its
In this code example, each pattern listed in the
$block_patterns = array() is called by
foreach() function which
patterns directory file with the listed pattern name in the array which we will add in the next step.
2.2: Adding a pattern file to the
Next, we should have all the listed patterns files in the
$block_patterns = array(). Here is an example of one of the pattern files,
Let’s reference the pattern in the
footer.html template part:
This is similar to adding heading or footer parts in a template file.
The patterns can similarly be added to the
parts/footer.html template by modifying it to refer to
slug of the theme’s pattern file (
Now, if we visit the patterns inserter of the block editor, the
Footer with background should be available for our use:
The following screenshot shows the newly created footer with background pattern on the front-end.
Now that patterns have become the integral part of block theme, many patterns are bundled in block themes — like Quadrat, Seedlet, Mayland, Zoologist, Geologist — following the workflow discussed above. Here is an example of the Quadrat theme
/inc/patterns folder with a block-pattern registration file and list of files with content source and required pattern header within
return array() function.
Section 2: Creating and loading patterns without registration
Please note that this feature requires the installation of WordPress 6.0 or Gutenberg plugin 13.0 or above in your site.
This new WordPress 6.0 feature allows pattern registration via standard files and folders –
/patterns, bringing similar conventions like
The process, as also described in this WP Tavern article, involves the following three steps:
A typical pattern header markup, taken from the article is shown below:
As described in the previous section, only
Slug fields are required and other fields are optional.
In the following steps, let’s explore how a
footer-with-background.php pattern registered with PHP and used in a
footer.html template is refactored.
2.1: Create a
/patterns folder at the root of the theme
The first step is to create a
/patterns folder at TT2 Gopher theme’s root and move the
footer-with-background.php pattern file to
/patterns folder and refactor.
2.2: Add pattern data to the file header
Next, create the following pattern header registration fields.
A pattern file has a top title field written as PHP comments. Followed by the block-content written in HTML format.
2.3: Add Pattern Content to the file
For the content section, let’s copy the code snippets within single quotes (e.g.,
'...') from the content section of the
footer-with-background and replace the
<!-- some-block-content /-->:
The entire code snippet of the
patterns/footer-with-background.php file can be viewed here on the GitHub.
Please note that the
block-patterns.php are extras, not required in WordPress 6.0, and included only for demo purposes.
2.4: Referencing the patterns slug in the template
Adding the above refactored
footer-with-background.php pattern to
footer.html template is exactly the same as described in the previous section (Section 1, 2.2).
Now, if we view the site’s footer part in a block editor or front-end of our site in a browser, the footer section is displayed.
Pattern categories and types Registration (optional)
To categorize block patterns, the pattern categories and types should be registered in theme’s
Let’s consider an example of registering block pattern categories from the TT2 Gopher theme.
After the registration, the patterns are displayed in the pattern inserter together with the core default patterns. To add theme specific category labels in the patterns inserter, we should modify the previous snippets by adding theme namespace:
footer-with-background pattern is visible in the patterns inserted with its preview (if selected):
This process greatly simplifies creating and displaying block patterns in block themes. It is available in WordPress 6.0 without using the Gutenberg plugin.
Examples of themes without patterns registration
Early adopters have already started using this feature in their block themes. A few examples of the themes, that are available from the theme directory, that load patterns without registration are listed below:
Section 3: Creating and using patterns with low-code
The official patterns directory contains community-contributed creative designs, which can be copied and customized as desired to create content. Using patterns with a block editor has never been so easier!
Any patterns from the ever-growing directory can also be added to block themes just by simple “copy and paste” or include in the
theme.json file by referring to their directory pattern slug. Next, I will go through briefly how easily this can be accomplished with very limited coding.
Adding and customizing patterns from patterns directory
3.1: Copy pattern from directory into a page
Here, I am using this footer section pattern by FirstWebGeek from the patterns directory. Copied the pattern by selecting the “Copy Pattern” button and directly pasted it in a new page.
3.2: Make desired customizations
I made only a few changes to the color of the fonts and button background. Then copied the entire code from the code editor over to a clipboard.
If you are not familiar with using the code editor, go to options (with three dots, top right), click the Code editor button, and copy the entire code from here.
3.3: Create a new file in /patterns folder
First, let’s create a new
/patterns/footer-pattern-test.php file and add the required pattern header section. Then paste the entire code (step 3, above). The pattern is categorized in the footer area (lines: 5), we can view the newly added in the pattern inserter.
3.4: View the new pattern in the inserter
To view the newly added
Footer pattern from patterns library pattern, go to any post or page and select the inserter icon (blue plus symbol, top left), and then select “TT2 Gopher – Footer” categories. The newly added pattern is shown on the left panel, together with other footer patterns and its preview on the right (if selected):
Registering patterns directly in
In WordPress 6.0, it is possible to register any desired patterns from the pattern directory with
theme.json file with the following syntax. The 6.0 dev note states, “the patterns field is an array of [pattern slugs] from the Pattern Directory. Pattern slugs can be extracted by the [URL] in single pattern view at the Pattern Directory.”
This short WordPress 6.0 features video demonstrates how patterns are registered in the
/patterns folder (at 3:53) and registering the desired patterns from the pattern director in a
theme.json file (at 3:13).
Then, the registered pattern is available in the patterns inserter search box, which is then available for use just like theme-bundled patterns library.
In this example, the pattern slug
footer-section-design-with-3-column-description-social-media-contact-and-newsletter from the earlier example is registered via
Page creation pattern model
As part of “building with patterns” initiatives, WordPress 6.0 offers a pattern modal option to theme authors to add page layout patterns into block theme, allowing site users to select page layout patterns (e.g., an about page, a contact page, a team page, etc.) while creating a page. The following is an example taken from the dev note:
This feature is currently limited to Page Post Type only and not for “Posts Post Type”, yet.
The page creation pattern modal can also be disabled completely by removing the post-content block type of all the patterns. An example sample code is available here.
You can follow and participate in GitHub’s discussion from the links listed under the resource section below.
Using patterns directory to build page
Patterns from the directory can also be used to create the desired post or page layout, similar to page builders. The GutenbergHub team has created an experimental online page builder app using patterns directly from the directory (introductory video). Then the codes from the app can be copied and pasted in a site, which greatly simplifies the building complex page layout process without coding.
In this short video, Jamie Marsland demonstrates (at 1:30) how the app can be used to create an entire page layout similar to page builder using desired page sections of the directory.
Patterns allow users to recreate their commonly used content layout (e.g., hero page, call out, etc.) in any page and lower the barriers to presenting content in styles, which were previously not possible without coding skills. Just like the plugins and themes directories, the new patterns directory offers users options to use a wide range of patterns of their choices from the pattern directory, and write and display content in style.
Indeed, block patterns will change everything and surely this is a game changer feature in the WordPress theme landscape. When the full potential of building with patterns effort becomes available, this is going to change the way we design block themes and create beautiful content even with low-code knowledge. For many creative designers, the patterns directory may also provide an appropriate avenue to showcase their creativity.
This content was originally published here.