Adding Block Patterns to Your Theme

Block patterns are unique, predefined combinations of blocks you can use and tweak to create stunningly designed sections of your website.

From global styles, to entirely block-based themes, the WordPress block editor is aiming high. Amongst the newest experimental features are block patterns. Block patterns are unique, predefined combinations of blocks you can use and tweak to create stunningly designed sections of your website.

The possibilities for block patterns are extremely exciting, especially for those of us providing tools to help people create their own websites. Patterns start to tackle the user question of, “How do I make my website look like this theme demo?”

By providing our users with predefined portions of layout, they can build and customize their own unique pages with a click — no coding or advanced block building knowledge required.

The Patterns API

Gutenberg 7.8 introduced a new, experimental API we can now use to register custom block patterns:

register_pattern(
    'my-plugin/hello-world',
    array(
        'title'   => __( 'Hello World', 'my-plugin' ),
        'content' => "<!-- wp:paragraph -->\n<p>Hello World</p>\n<!-- /wp:paragraph -->",
    )
);

View Documentation

The API really only contains two things: a name for your pattern, and the raw HTML output that you can copy and paste from the Code editor view. This means you can design your patterns straight in the editor, no coding knowledge required.

When you add a new pattern to your theme, it shows up in a new sidebar in the editor, along with any other pattern you might have installed:

Note: The new Block Pattern sidebar is a temporary proof-of-concept and is subject to change.

Using this API, we can start to introduce block patterns into our themes.

Adding Block Patterns to Twenty Twenty

Let’s take a look at adding a block pattern to the Twenty Twenty theme.

The Twenty Twenty demo site showcases content that highlights the strengths of the theme. We can grab some of that content, and make it into a pattern that can be included with the theme. Now, rather than trying to replicate the site demo by hand, people using Twenty Twenty can insert the pattern directly into their own sites.

On the homepage, one of the sections that catches my eye is the exhibitions list, which is a mix of images and text displayed in a grid. Not only does it look great, the combination of content is generic enough to be used for many different purposes, making it an ideal pattern to abstract out for reuse.

The Twenty Twenty theme demo, showing a section of the page in which four items are arranged in a 2 column grid. The top two are fully visible, and each column contains an abstract red image, a heading, a large paragraph, and then a button that says "Read More."

Let’s break this content down into its basic blocks:

__ Columns
____ Column
________ Image
________ Heading
________ Paragraph
________ Button
____ Column
________ Image
________ Heading
________ Paragraph
________ Button

The Columns block here acts as a wrapper for the exhibitions content, and provides a structure for it to collapse down into one column on smaller screens.

The single Columns block is the smallest atomic unit we can include to make this a complete pattern. Even if the demo shows multiple rows of exhibitions, we’ll stick to just this single row of two items. If someone wanted to add a bunch of exhibitions on their own website, they could reuse this pattern multiple times.

In order to convert this into a block pattern, we’ll need to grab the HTML output from the block in the Code view of the editor:

The WordPress editor, open to the Code editor view. The settings menu is open to show where you can toggle on the Code editor.

We need to copy this HTML, escape it, and add it to a register_pattern function inside of Twenty Twenty’s functions.php file.

(I’ve used onlinestringtools.com to escape the raw html output, but there are also code editor tools that can do this.)

/**
 * Register Block Patterns.
 */
 
register_pattern (
    'twentytwenty/exhibitions-pattern',
    array (
        'title'   => __( 'Two columns of mixed content', 'twentytwenty' ),
        'content' => "<!-- wp:columns {\"align\":\"wide\"} -->\n<div class=\"wp-block-columns alignwide\"><!-- wp:column -->\n<div class=\"wp-block-column\"><!-- wp:image {\"sizeSlug\":\"large\"} -->\n<figure class=\"wp-block-image size-large\"><img src=\"https://2020.wordpress.net/wp-content/uploads/2019/10/2020-three-quarters-1.png\" alt=\"\"/></figure>\n<!-- /wp:image -->\n\n<!-- wp:heading -->\n<h2>Works and Days</h2>\n<!-- /wp:heading -->\n\n<!-- wp:paragraph {\"fontSize\":\"larger\"} -->\n<p class=\"has-larger-font-size\">August 1 – December 1</p>\n<!-- /wp:paragraph -->\n\n<!-- wp:buttons -->\n<div class=\"wp-block-buttons\"><!-- wp:button {\"className\":\"is-style-outline\"} -->\n<div class=\"wp-block-button is-style-outline\"><a class=\"wp-block-button__link\">Read More</a></div>\n<!-- /wp:button --></div>\n<!-- /wp:buttons --></div>\n<!-- /wp:column -->\n\n<!-- wp:column -->\n<div class=\"wp-block-column\"><!-- wp:image {\"sizeSlug\":\"large\"} -->\n<figure class=\"wp-block-image size-large\"><img src=\"https://2020.wordpress.net/wp-content/uploads/2019/10/2020-three-quarters-2.png\" alt=\"\"/></figure>\n<!-- /wp:image -->\n\n<!-- wp:heading -->\n<h2>The Life I Deserve</h2>\n<!-- /wp:heading -->\n\n<!-- wp:paragraph {\"fontSize\":\"larger\"} -->\n<p class=\"has-larger-font-size\">August 1 – December 1</p>\n<!-- /wp:paragraph -->\n\n<!-- wp:buttons -->\n<div class=\"wp-block-buttons\"><!-- wp:button {\"className\":\"is-style-outline\"} -->\n<div class=\"wp-block-button is-style-outline\"><a class=\"wp-block-button__link\">Read More</a></div>\n<!-- /wp:button --></div>\n<!-- /wp:buttons --></div>\n<!-- /wp:column --></div>\n<!-- /wp:columns -->",
    )
);

When we go over and create a new page or post, we now see this pattern listed in the Block Patterns sidebar:

The WordPress editor, with the Block Patterns sidebar open. The newly registered two-column pattern is highlighted within the sidebar.

Voilà! Twenty Twenty now comes with a pattern.

You can view these changes in the Theme Experiments GitHub repo.


You can add any number of patterns to your theme, and even unregister core patterns if you only want your patterns to be available to people using your theme. Create some great patterns that show off just what your theme is capable of! The only limitation is your imagination.

Have you added patterns to your theme already? Tell us about it 👇

What Developers Need to Know About Theme Design

Making a theme is really exciting. It’s a great way to practice your coding skills. It could be a good way to bring in some extra pocket change. Best yet, seeing someone use something you’ve built is incredibly rewarding.

I’ve watched the quality of theme design get better and better in the WordPress.org directory in the last few years, but I still see a lot of themes that look the same. Free themes still lag behind premium themes in terms of design quality. You can help change all that. You don’t need a design background to make good design decisions: a developer conscious of design can still make a good-looking theme.

Here are a few general tips and tricks you can apply to your themes to give them a solid design base, regardless of your background.

Pick a Direction

When planning out your new theme, have a specific user or use case in mind. That use case shouldn’t be “a theme for everyone.” Your use case can still be pretty broad — “a modern theme for small businesses” is still targeted enough for your ideal user to solve a specific goal by using your theme. Alternately, you can get super specific, giving yourself a prompt like “a food blogging theme targeting smartphone photographers.” Each theme idea has a different set of constraints, and by embracing and sticking to these constraints, you can make better themes.

Once you have a direction in mind, think through that scenario and what your target users would need. The more you imagine how people are going to use your theme, the stronger your concept becomes.

For a modern business theme, think about what a great business website needs. If the company has a physical location, site visitors need an easy way to find an address or directions. People visiting the site need a way to contact the business, via phone, email, or contact form. The theme needs strong page templates, but probably not a unique blog template. It probably needs a navigation bar that can support up to a dozen or more pages at various levels. Typography should probably be strong and serious. A business might also need to display their products, so you could consider adding support for popular e-commerce plugins.

On the other hand, an amateur food blogger, especially if they don’t have a nice camera, needs a theme that focuses more on super strong typography. Photos should be present, but de-emphasized in case they aren’t top-quality. The theme’s users need a way to easily display recipes. Maybe this means building a plugin that pairs with the theme for extra feature support, or maybe it means really nice post styling. A variety of page templates probably aren’t extremely important, but well-styled category archive templates are. Type can have a little more personality, but still has to be readable.

In both situations, you want to have a strong responsive design so site visitors can browse on their phones or tablets. After all, 50% of web traffic comes from mobile devices.

Look at other themes and websites that fit within your use case. Find five really great ones and figure out what makes them great. Take these insights and apply them to your theme.

Visual Design

Typography

Typography is probably the most important part of the vast majority of themes. What’s a site without text? Type needs to be clear, readable, and context-appropriate. There’s a couple rules of thumb you can use to make sure your theme’s typography looks good.

The hardest part of theme typography is picking the right fonts. The “popular” sorting option on Google Fonts is a surprisingly okay place to start looking for a font to use. Try to pick fonts that have multiple weights. Depending on the font, a light or semibold weight might be more appropriate than just regular or bold. At the very least, avoid using fonts that don’t come with bold or italic. There is (finally)! a “number of styles” filter in Google Fonts that you can also browse through. Don’t trust Google’s recommended font pairings — they’re actually pretty poor.

If you want to combine a serif and a sans-serif and you’re unsure which typefaces to pick, go for a font family. These are built to have similar features and will naturally pair well. Some families on Google Fonts include Merriweather Sans and Serif, PT Sans and Serif, and Noto Sans and Serif.

When in doubt, use font combinations from sites you like.

Once you’ve chosen your font(s), you need to style your text to be readable. This means using appropriate font sizing. Don’t make someone squint! Use at least 14px or higher for your body text. If 14px looks too small, don’t be afraid to go up to 16px, or even 18px.

One of the biggest issues I see concerning type on themes is an overall lack of line height, which is the space between each line of text. As a general rule of thumb, my headers are always between 1.2-1.4 the size of my font, and my body text is almost always between 1.4-1.6 the size of your font. And the awesome thing about line-height is you can even just use line-height: 1.4 instead of having to calculate the actual pixel value.

As a general rule, paragraphs shouldn’t be more than 50- 75 characters long. This helps keep them nice and readable.

Finally, limit the number of font styles. I mentioned earlier that you should look for fonts that have multiple font weights. While you should seek these out, don’t combine too many different font weights and sizes, since they negatively impact your content’s hierarchy and flow.

Color

There is a lot of psychology around color. You don’t need to be an expert in color, but learn a little bit before you pick them for your theme. Colors also have different meanings in different cultures, so keep your audience in mind when picking your palette. For a good introduction to color theory, watch Aaron Jorbin’s presentation on WordPress.tv.

Color also affects whether or not your users will be able to view your theme. Keep in mind contrast when designing your themes — contrast that’s too high or too low makes it hard for people, especially people with visual impairments, to read your text and navigate through the site. Keep in mind people with low vision or color blindness.

Don’t use too many bright or bold colors. They’re great for emphasis and drawing attention to specific parts of the page, but too many strong colors can make your theme hard to look at, or can make it difficult for people to find the most important content on the page.

Soften your blacks. Pure black doesn’t really exist in the world around us, and pure black on the web ends up looking harsh and unnatural. Add hints of color to your black by going up and right in most color pickers, or go for a dark grey.

If you’re struggling with color, here’s some things you can do:

  • Stick to dark text on a light background with one or two accent colors. You can’t go wrong with dark grey text on white.
  • Use a site like Adobe Color or Colour Lovers to find nice palettes.
  • Borrow color palettes from sites you like.

Whitespace

Let everything breathe. Use ample white space between separate elements in your theme.

Finding the right balance of whitespace is hard. When in doubt, l o o s e n  t h i n g s  u p  a  l i t t l e. (Just not your lowercase text — only add letter spacing to uppercase text.)

Details

Don’t go crazy with the details. Less is more.

For example, consider if the drop-shadow you’re using adds a necessary sense of depth to your theme, or if it’s purely decorative. If it’s necessary, tone it down a little. In general, don’t use drop-shadows darker than 25% opacity. The same can be said for gradients; try to keep gradients subtle.

Use animation sparingly. I mean really sparingly. Inappropriate animation is jarring and detracts from your theme. Motion should only be used to show change, not for decoration.

UX Design

There is nothing worse than finding a theme that looks awesome and does what you need, only to install and activate it and find a thousand options you need to hand-configure to make it look like the demo.

Many of WordPress’s core philosophies revolve around simplicity and ease of use:

  • Great software should work with little configuration and setup.
  • Design for the majority.
  • Decisions, not options.
  • Clean, lean, and mean.
  • Striving for simplicity.

You should take these core philosophies to heart when creating your themes. Cut the number of options down to what’s absolutely necessary. For example, instead of letting people control every single color in your theme, let them choose two or three and generate a color scheme based on those colors. Make smart defaults and informed assumptions. If you include options that can be previewed, put them in the Customizer. Stop using gigantic theme options and settings pages. They are almost universally a bad experience for users.

Lastly — user test! If you’re creating a premium theme, you owe it to your users to make your theme as easy to set up and use as possible. UserTesting.com is relatively cheap and easy. Running as few as 3 user tests will catch the majority of your theme’s issues.

Free theme? No budget? Ask around for some beta testers. Don’t want to? Then at the very least, set up your theme on a couple different demo sites. Try it on one totally new, empty site, and then try setting it up on a site that already has content. Record your screen as you set it up. If you did well and remembered where everything was — awesome! You can now use that video as documentation. Did you struggle? Figure out where the process broke down, and fix it.

Love the idea of user testing? Read Rocket Surgery Made Easy by Steve Krug. It’s short, concise, and explains everything you need to know to run a good user test.

You don’t need to be a designer to make a good theme — you just need to be conscious of your design decisions. Now go forth and theme!