With each WordPress and Gutenberg release, the Patterns API gets more and more powerful. And, as a theme author and designer, the new use cases you keep surfacing in turn keep helping drive development forward.

Since the Gutenberg 15.5 release, you can register template-specific patterns that your theme’s users can use when adding a new template.

This feature had been in the works over several Gutenberg releases. Version 14.9 began by letting you register patterns for specific template types. Then, in 15.2, you could select from a fallback or empty template via a start modal at the point you added a new template from the Site Editor. Gutenberg 15.5 brought these two concepts together: your template patterns now show up in the modal.

The question now: What can you build with this new feature of the Patterns API?

This tutorial will focus on creating multiple front-page designs that your users can choose from. Specifically, you will learn to build patterns that are tied to the Front Page template in WordPress.

You can also use the process in this post to build patterns for any template type. This will give your users more choices and more control over their sites.

Registering patterns for template types

Before moving forward, you should already be familiar with registering custom patterns. The technique used in this tutorial registers patterns by placing them in your theme’s /patterns folder.

Here’s the code for a basic pattern file, which includes the new Template Types header:

<?php
/**
 * Title: Your Pattern Title
 * Slug: themeslug/pattern-slug
 * Categories: posts
 * Template Types: front-page
 */
?>
<!-- Your pattern code goes here. -->

The Template Types header accepts a single value or a comma-separated list of template types. For example, if you wanted to make the pattern available to both Front Page and Page, the code would be:

<?php
/**
 * Title: Your Pattern Title
 * Slug: themeslug/pattern-slug
 * Categories: posts
 * Template Types: front-page, page
 */
?>
<!-- Your pattern code goes here. -->

In this tutorial, you will work with the front-page template. But, feel free to use any of these default template types for other patterns you want to build:

• index
• home
• front-page
• singular
• single
• page
• archive
• author
• category
• taxonomy
• date
• tag
• attachment
• search
• privacy-policy
• 404

Building a custom front-page pattern

In this tutorial, you will build a simple pattern for the front-page template type, as you see here:

Your theme users can select this pattern when they’re adding a Front Page template via Appearance > Editor > Templates in the WordPress admin. Once you’ve mastered the basics, you can add as many patterns as you want, even hundreds of them—but let’s be reasonable!

Now use what you learned in the previous section to build a new pattern. Create a file named hero.php and place it in your theme’s /patterns folder with this code (be sure to change themeslug to match your theme’s slug):

<?php
/**
 * Title: Hero
 * Slug: themeslug/hero
 * Categories: posts
 * Template Types: front-page
 */
?>
<!-- Your pattern code goes here. -->

Because this pattern is for a specific template type, it will represent the entire front-end view for the page that uses it. Depending on your design, you will often need to include common template parts like the header and footer.

Your initial pattern code may be something like this:

<?php
/**
 * Title: Hero
 * Slug: themeslug/hero
 * Categories: posts
 * Template Types: front-page
 */
?>
<!-- wp:template-part {"slug":"header","tagName":"header","theme":"themeslug"} /-->

<!-- Your pattern code goes here. -->

<!-- wp:template-part {"slug":"footer","tagName":"footer","theme":"themeslug"} /-->

Note the use of the theme attribute in the code. When you include template parts in a pattern, you must set this attribute to your theme slug. Otherwise, the editor will throw a “missing template part” error. There is an open ticket to address this issue.

WordPress does not yet have a built-in pattern manager/builder. The easiest way to create a custom one is to create it in Site Editor or Template Editor and copy the block code into the pattern file. Or you could build this with the post/page editor (note: you can’t add template parts in this editor).

The pattern shown in the earlier screenshot has four components:

• Header template part
• Cover block with nested Heading, Paragraph, and Buttons blocks
• Query Loop block
• Footer template part

Try your hand at recreating it from the editor. Or flesh out a design that you prefer. 

💡 Tip: you can copy all of the block code from the editor by clicking the : (Options) button and selecting Copy all blocks.

If you get stuck along the way, copy and paste this code into your theme’s /patterns/hero.php file and customize it:

<?php
/**
 * Title: Hero
 * Slug: themeslug/hero
 * Categories: posts
 * Template Types: front-page
 */
?>
<!-- wp:template-part {"slug":"header","tagName":"header","theme":"themeslug"} /-->

<!-- wp:cover {"minHeightUnit":"vh","gradient":"vivid-cyan-blue-to-vivid-purple","isDark":false,"align":"full","textColor":"white","layout":{"type":"constrained"}} -->
<div class="wp-block-cover alignfull is-light has-white-color has-text-color"><span aria-hidden="true" class="wp-block-cover__background has-background-dim-100 has-background-dim has-background-gradient has-vivid-cyan-blue-to-vivid-purple-gradient-background"></span><div class="wp-block-cover__inner-container"><!-- wp:spacer {"height":"60px"} -->
<div style="height:60px" aria-hidden="true" class="wp-block-spacer"></div>
<!-- /wp:spacer -->

<!-- wp:heading {"textAlign":"center","align":"wide","style":{"typography":{"lineHeight":"1.1","fontSize":"5rem"}}} -->
<h2 class="wp-block-heading alignwide has-text-align-center" style="font-size:5rem;line-height:1.1">A Radical  Experience</h2>
<!-- /wp:heading -->

<!-- wp:paragraph {"align":"center","style":{"typography":{"fontSize":"1.4rem"}}} -->
<p class="has-text-align-center" style="font-size:1.4rem">This blog documents my travels around the world. Follow along if you want to experience the adventure of a lifetime.</p>
<!-- /wp:paragraph -->

<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
<div class="wp-block-buttons"><!-- wp:button {"className":"is-style-outline"} -->
<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button">More About Me →︎</a></div>
<!-- /wp:button --></div>
<!-- /wp:buttons -->

<!-- wp:spacer {"height":"60px"} -->
<div style="height:60px" aria-hidden="true" class="wp-block-spacer"></div>
<!-- /wp:spacer --></div></div>
<!-- /wp:cover -->

<!-- wp:group {"align":"full","style":{"spacing":{"padding":{"top":"2em","right":"2em","bottom":"2em","left":"2em"}}},"layout":{"type":"default"}} -->
<div class="wp-block-group alignfull" style="padding-top:2em;padding-right:2em;padding-bottom:2em;padding-left:2em"><!-- wp:query {"queryId":10,"query":{"perPage":3,"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","author":"","search":"","exclude":[],"sticky":"","inherit":false},"displayLayout":{"type":"flex","columns":3}} -->
<div class="wp-block-query"><!-- wp:post-template -->
<!-- wp:post-title {"level":3,"isLink":true} /-->

<!-- wp:post-featured-image {"isLink":true,"aspectRatio":"1","align":"wide"} /-->

<!-- wp:post-excerpt {"excerptLength":16} /-->

<!-- wp:separator -->
<hr class="wp-block-separator has-css-opacity"/>
<!-- /wp:separator -->

<!-- wp:post-date /-->
<!-- /wp:post-template --></div>
<!-- /wp:query --></div>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer","theme":"themeslug"} /-->

Creating a front page from a pattern

At the moment, the purpose of template patterns is to give your users a starting point for new templates. Theoretically, this could evolve to replacing existing templates wholesale in the future, but the feature doesn’t let you do that yet. So for now, you can only use template patterns when you first add a new template in the Site Editor.

Go to Appearance > Editor in the WordPress admin and click on the Templates item. Then, click the + (Add New Template) button and select Front Page, as you see here:

This should open the editor with a start modal for selecting a pattern. You should see your custom pattern in the list, as below:

Once you select your custom pattern, WordPress will add it to the editor’s content canvas. From there, you (or your users) can edit it further.

---

All that’s really left to do is create more patterns. Once this feature lands in WordPress, it will give you a ready solution to the age-old problem with theming: How do I offer my users a variety of template options? This issue is central to front-page design, which is why it was the focus of this post. But, don’t limit yourself to just one template type. Go out and explore as many as you like.

Props to @marybaum and @annezazu for feedback and review. Photos by @mbigul, @rmartinezduque, and @eaglethemes from the WordPress photos directory.