WordPress.org

WordPress Developer Blog

Adding starter patterns to your WordPress themes

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:

<?php
/**
 * 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:

<?php
/**
 * 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:

<?php
/**
 * 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!

<?php
/**
 * 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.

Categories:

6 responses to “Adding starter patterns to your WordPress themes”

  1. António Carreira Avatar
    António Carreira

    It kills me that we can’t have fully synced patterns from PHP files. Just imagine the power of fully synced patterns combined with PHP.

    What if I want to create a pattern for a header where the logo is dynamic, for instance? I could create a pattern with a bit of PHP inside to render whatever dynamic information I need.
    A few days later the client asks for a different color on the header. No problem, just edit your php pattern file and it will update sitewide.
    Nope. It won’t. As soon as you place a pattern on the editor it loses the connection to the original file and becomes a bunch of static blocks.

    The workaround? Create custom dynamic blocks. Does it work? Yeah, sure, but that’s a hell of a workaround…

    1. Justin Tadlock Avatar

      One workaround is to use the new Block Bindings API coming in WordPress 6.5 (part 1 of a tutorial series on this feature is already published). Granted, it won’t specifically work with the Site Logo block in WP 6.5.

      But you could also potentially filter render_block_core/site-logo to avoid a custom block in this specific situation.

      Synced patterns for theme authors is definitely something that’s highly requested. Please add your support and feedback to this ticket.

      1. António Carreira Avatar
        António Carreira

        Oh, I thought I was alone on this one and probably missing something really obvious. Thanks for the heads up.

        I mentioned the logo block, but it could be anything. It could be the entire header area or whatever. Man, sometimes I miss the good old header.php and footer.php.

        Being able to render stuff dynamically is what makes WordPress themes so powerful.

        I’m ok with transitioning to a JS/React approach. Coming from a self taught PHP background, learning how to build custom blocks from scratch was a bit of a nightmare, but here I am, building custom blocks for everything and anything.
        Having said that, we should be able to add dynamic stuff to our themes without the need for custom blocks.

  2. metaphorcreations Avatar

    Hey, Justin – Can starter patterns be added to custom post types? And also by using register_block_pattern() as opposed to a php file with header values?

    I’ve been trying to implement this, but can’t seem to figure it out. Thanks!

    1. Justin Tadlock Avatar

      Yes. For the Post Types header field, you can add the slug for your post type instead of or in addition to page. You can add these for any post type that supports the Block Editor.

Leave a Reply

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