WordPress Developer Blog

Adding starter patterns to your WordPress themes

If you’ve ever sat in front of a blank screen and wondered where to start, you have a lot in common with your users. And you can help them over the hump with starter patterns, which come in two flavors:

  • Page patterns: These selectable patterns appear when you create a new post, page, or custom post type entry. (Added in WordPress 6.0.)
  • Template patterns: Also selectable, these show when you create a new template from the Site Editor. (Added in WordPress 6.2.)

Never heard of starter patterns? That’s OK. We’ll get to how these work and why you should be using them.

In this post, we’ll explore how these features work by using the default Twenty Twenty-Four theme. Please install and activate it to follow along.

This tutorial assumes that you already have a working knowledge of building custom patterns in WordPress. If you’re new to patterns, hop over to the documentation in the Theme Handbook. Then come back to finish this post.

Starter page patterns

Page patterns let you create custom patterns your users can access when they add a new page via Pages > Add New in their WordPress admin. At that point, a modal will pop up, covering the screen, and show them a wide selection of patterns, like this:

Now users have a lot of great options for starting a new page, without having to build every layout block by block.⁠

That’s a stated philosophy in the WordPress project, by the way. And one benefit of it is that even very seasoned designers are likely to discover some new options as the patterns page evolves over time.

Meanwhile, back to the page at hand: go ahead and choose the About pattern. It automatically shows up in the content area of the editor, ready for you to make it your own:

Let’s take a look at how this is happening behind the scenes in Twenty Twenty-Four. If you open the corresponding pattern file (patterns/page-about-business.php), you will see this code:

 * Title: About
 * Slug: twentytwentyfour/page-about-business
 * Categories: page
 * Keywords: starter
 * Block Types: core/post-content
 * Post Types: page, wp_template
 * Viewport width: 1400
<!-- Block code here. -->

Notice two important file header values there:

  • Block Types: A comma-separated list of block types this pattern is registered for. Must include core/post-content.
  • Post Types: A comma-separated list of post types this pattern should be used for.

Combining these two fields in this way turns them into a page pattern. Specifically, when Block Types includes core/post-content and Post Types is set to any valid post type, the pattern will appear as an option anytime you start a new post or page.

This works with any post type, including custom post types. Suppose you created a pattern that you wanted to be insertable for posts, pages, and products. You’d need to include each of the post types in the Post Types list, separated by commas:

 * Title: Example
 * Slug: themeslug/your-pattern-slug
 * Block Types: core/post-content
 * Post Types: page, post, product
<!-- Block code here. -->

Want some inspiration? The Twenty Twenty-Four theme has a lot of great page patterns:

  • Homepage patterns:
    • Blogging home
    • Business home
    • Portfolio home image gallery
    • Portfolio home with post featured images
  • Newsletter landing
  • Portfolio project overview
  • RSVP landing

It is good practice to name your pattern files using a standard scheme that will let you manage them over the long term. The Twenty Twenty-Four theme prefixes its page pattern files with page-.

Starter template patterns

Similar to page patterns, template patterns give users a starting point when you’re building a new template. The difference is that template patterns work from the Site Editor.

Go to Appearance > Editor > Templates in your WordPress admin and click the + icon button for creating a new template. When the modal appears, select the Front Page option:

This will take you to the Template Editor for creating your Front Page template. A modal will appear over the screen with several options for building your site’s front page:

The major benefits of this feature are the same as page patterns. The goal is to give users a smoother onramp to creating templates, even if they have very little experience laying out a page on their own. And as with page patterns, even seasoned designers might find some new and different approaches.

Let’s take a look at one of Twenty Twenty-Four’s template patterns that works for the Front Page. Open patterns/template-home-blogging.php. Here’s what the file header looks like:

 * Title: Blogging home template
 * Slug: twentytwentyfour/template-home-blogging
 * Template Types: front-page, index, home
 * Viewport width: 1400
 * Inserter: no
<!-- Block code here. -->

Again, take note of these two important fields:

  • Template Types: A comma-separated list of template types this pattern is registered for.
  • Inserter: Whether to show the pattern in the inserter. Generally, you would set this to no since template patterns aren’t meant to be used within post content. It would also hide the pattern from the Patterns library.

As you can see, this particular pattern is available when creating a new front page, index, or home template. But WordPress has several default template types to choose from:

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

You can always get the most up-to-date list of default template types from the get_default_block_template_types() function reference. And the Template Hierarchy documentation in the Theme Handbook is a good reference for which templates are shown under various scenarios on the front end.

The Twenty Twenty-Four theme prefixes its template pattern files with template-. Like page patterns, it is always a good idea to use a standard naming convention for long-term maintenance.

Tips on reusing patterns

One of the cornerstones of good development is code reuse. Basically, there is no good reason to recreate the same block markup in multiple places if you can help it.

A pattern in WordPress is just a block (<!-- wp:pattern /-->). That means you can use one or more of them anywhere that block markup is parsed and rendered. Let’s look at a couple of good practices that will make it easier to manage your starter patterns (and other patterns in general).

Nest “normal” patterns in your starter patterns

Yes, you can absolutely put patterns in your patterns in your patterns.

Take a look at Twenty Twenty-Four’s patterns/page-about-business.php file again. Notice anything? The only block markup in the code is calls to other patterns!

 * Title: About
 * Slug: twentytwentyfour/page-about-business
 * Categories: page
 * Keywords: starter
 * Block Types: core/post-content
 * Post Types: page, wp_template
 * Viewport width: 1400

<!-- wp:pattern {"slug":"twentytwentyfour/text-title-left-image-right"} /-->
<!-- wp:pattern {"slug":"twentytwentyfour/text-project-details"} /-->
<!-- wp:pattern {"slug":"twentytwentyfour/cta-services-image-left"} /-->
<!-- wp:pattern {"slug":"twentytwentyfour/team-4-col"} /-->
<!-- wp:pattern {"slug":"clients-section"} /-->
<!-- wp:pattern {"slug":"twentytwentyfour/text-faq"} /-->
<!-- wp:pattern {"slug":"twentytwentyfour/cta-content-image-on-right"} /-->

This is a great way to break up a large template into sections. It has two advantages:

  • You don’t have to repeat code written elsewhere, which means less maintenance and bugs over the long haul.
  • Users can insert those other patterns as individual sections elsewhere on their site.

Use starter patterns in your templates

If you’re already building full template patterns, you should also exploit this nesting feature to reuse your own patterns in lots of places across your theme—for instance, inside your theme templates.

Not only will you save code time and keystrokes, but your theme will automatically look more consistent and polished, with NO extra thought!

Open the Twenty Twenty-Four theme’s templates/home.html file, which represents the blog posts index (blog page). There is literally one line of code that calls for an existing pattern:

<!-- wp:pattern {"slug":"twentytwentyfour/template-home-business"} /-->

A big win for the DRY (Don’t Repeat Yourself) principle!

Plus, calling existing patterns gives you an instant superpower: you can write PHP in them. That opens up a world of other possibilities. But we’ll save that for another post on another day.

For now, go forth and build some cool starter patterns for your pages and templates.

Props to @bph and @marybaum for feedback and review on this post. And a special thanks to everyone who worked on Twenty Twenty-Four for providing great patterns.


Leave a Reply

Your email address will not be published. Required fields are marked *