Skip to main content

January 18th, 2023

Utilizing Patterns vs. Building Custom ACF Blocks

When working with a tool like ACF to build custom blocks in WordPress, sometimes the line gets a bit blurry on what should be a pattern vs. what makes sense to just build as a custom block or when to utilize something like a block template or InnerBlocks template. Ultimately, they’re all trying to simplify the process of adding new sections to a site, they just vary a bit in their approach so you may think it doesn’t really matter which route you choose. However, if you’re ignoring patterns completely, you may be spending development time building unnecessary custom blocks in your builds that could easily be executed with a pattern. Let’s take a closer look so you can identify opportunities to leverage patterns in your WordPress projects.

What are block patterns?

Block patterns are predefined layouts made up of individual blocks. If each block is an ingredient, the pattern is the recipe. No one wants to tell their client, “If you want a section like this, you need to first add Block A, then you need to add 3 of Block B, then add a spacer before Block C, etc. etc.” You can almost feel their eyes glazing over even thinking about it.

Instead, it’s much easier to give them a visual preview of some finished “recipes” under the Patterns section of the editor for them to easily choose from and clicking this one area will set up the blocks in the order they need allowing them to focus on the content.

How do you register a block pattern?

If you are running at least WordPress 6.0, the easiest way to register new patterns is by creating a “patterns” folder in your theme. If you place pattern markup in this location, you do not need to use the register_block_pattern function for each pattern.

Within the patterns subfolder of your theme, you’ll create a file for each pattern you want to register. Within this file, you’ll be placing some basic information about the pattern, as well as the pattern markup.

Let’s say you’re building a simple call-to-action pattern with a header, paragraph, and button block, that looks something like this:

You could just create an ACF block for this entire area and that does work. However, the editing experience of ACF blocks is a little different from native blocks and it’s always great to lean on core functionality as much as possible. That being said, let’s execute this with a pattern since its “ingredients” are all native core blocks (heading, paragraph, buttons) vs. building a custom block for it.

To start, let’s just create a file called cta.php within the /patterns/ folder of our theme. Inside that file, let’s start with some information that any registered pattern should include:

 * Title: Call-to-Action
 * Slug: your-theme-prefix/cta
 * Categories: text

When registering a pattern via a patterns subfolder, title and slug are all that’s required, but you can also use things like:

  • keywords: An array of searchable keywords to help find the registered pattern
  • viewportWidth: Under the patterns area of the inserted in the block editor, you’ll see a visual preview of each pattern. viewportWidth allows you to specify the intended width the pattern displays at in the area
  • blockTypes: An array of block types that the pattern is intended to be used with
  • postTypes: An array of post types to limit the pattern’s use to. The pattern will only be available when editing one of the post types passed on the array, for all the other post types the pattern is not available at all.
  • inserter: Registered patterns appear in the block inserter by default. By setting inserted to false, you can restrict a pattern to only be used programmatically.

So we have the starter file for the pattern registration, now we just need to add the pattern’s markup underneath this data.

How do you get a WordPress pattern’s markup?

If you don’t feel comfortable in code, there are plugins that exist that can help you create block patterns, including the markup needed. If you search “block pattern builder” in the WordPress repository, you’ll find a couple options there. Registering new patterns is easy to do, however, and there’s a way to build your pattern visually and use that to simplify creating the pattern markup needed so let’s cover those steps as minimizing plugin usage is always a thumbs up in my book.

Start by building out your pattern visually on a page or post. This is both a great way to generate the markup needed to register a pattern, as well as ensures you have all the parts needed for your pattern in place.

When viewing any page created in the block editor, including the page or post your pattern has been created on, WordPress defaults to the visual editor. It is possible to switch to the code editor, similar to how you could toggle between Visual and HTML in the old WYSIWYG classic editor in WordPress.

To do this, look in the upper right of the edit screen, you’ll see three dots that allow you to open up some editor options. One of these options allows you to switch from the visual view to the code view. When you’re using the Code Editor view, you’ll see the markup for your blocks that you can copy and paste for your pattern’s use.

Place the markup for the blocks in the cta.php right under the previous data, so the final file looks similar to:

 * Title: Call-to-Action
 * Slug: your-theme-prefix/cta
 * Categories: text
<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group"><!-- wp:heading {"textAlign":"center"} -->
<h2 class="has-text-align-center">This is a sample pattern</h2>
<!-- /wp:heading -->

<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">With a paragraph beneath the header</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">And a button</a></div>
<!-- /wp:button --></div>
<!-- /wp:buttons --></div>
<!-- /wp:group -->

Upon refreshing the block editor, you should see your newly created Pattern in the Patterns tab when you go to the block editor inserter.

How do you disable WordPress patterns?

If you don’t like WordPress patterns and have more comfort working with other tools like block templates and building this type of functionality into custom blocks, you can most definitely take that approach. If doing so, disabling built-in patterns may be a route to consider to avoid cluttering up the block editor with items not being actively used. Core WordPress patterns can be disabled entirely with:


Likely you have other declared theme supports in your theme’s functions file that this can be grouped with to disable the core block editor patterns added to any project. Even if utilizing patterns, you may want to remove the default core block patterns the block editor has by default to focus only on custom patterns.

An important note about patterns

One important thing to note about patterns is patterns do not stay linked to the content generated from them once inserted. What I mean by that is if you make a change to a pattern, it will only apply to future patterns inserted. It does not impact any previous areas generated from the pattern. The pattern is just a blueprint used for assembling blocks. Once those blocks are assembled, that process is completely over and no link between the two persists.

Now, there is discussion in WordPress core about creating some kind of syncing system for patterns, but it doesn’t exist yet. Given this, you do need to be careful in what kinds of content you explore implementing as patterns.

Whether you’re leaning into using patterns or not, understanding the use case for them and the simplicity behind registering them at least allows you to best weigh out all available approaches and make the best choice for your next WordPress project.

Get the latest in your inbox