Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 68 ยท Block Themes and the Site Editor

Block Patterns

Learn how block patterns work in WordPress block themes, from the patterns directory and PHP headers to categories, synced patterns, overrides and locking.

A block pattern is a saved arrangement of blocks that an author can insert with one click: a hero section, a pricing table, a row of testimonials. Patterns are the main way a block theme gives editors ready-made layouts without asking them to build every section from scratch. They are plain block markup with a bit of metadata, so a pattern is easy to write, easy to share and easy to change after it is inserted.

In this lesson you will see where patterns live in a theme, how to register them from PHP, how categories work, and how synced patterns and pattern overrides let one design appear in many places. You should already know what block markup looks like from Block Templates and Template Parts and how a theme is laid out from Block Themes: The Big Picture.

What a pattern is

A pattern is a string of serialized block markup, the same comment-delimited HTML you write in a template file. Inserting a pattern pastes those blocks into the page, and from then on they are ordinary blocks. Editing the page does not change the pattern, and editing the pattern does not change pages that already used it. That is the key difference from a synced pattern, which you will meet below.

flowchart LR
    P["Pattern<br/>(registered markup)"] -->|"insert"| A["Page A<br/>own copy of blocks"]
    P -->|"insert"| B["Page B<br/>own copy of blocks"]
    S["Synced pattern<br/>(wp_block post)"] -->|"reference"| C["Page C<br/>shows the shared blocks"]
    S -->|"reference"| D["Page D<br/>shows the shared blocks"]

A normal pattern is copied into each page; a synced pattern is referenced, so all pages show the same content.

The patterns directory

The simplest way to add patterns to a block theme is to put one PHP file per pattern into the theme's patterns/ folder. WordPress scans that folder and registers every file it finds. Each file starts with a header comment that carries the metadata, followed by the block markup.

PHP
<?php
/**
 * Title: Call to action
 * Slug: northwind/call-to-action
 * Description: A centered heading, a sentence and a button.
 * Categories: call-to-action
 * Keywords: cta, banner, signup
 * Viewport Width: 1200
 * Block Types: core/group
 */
?>
<!-- wp:group {"align":"full","layout":{"type":"constrained"}} -->
<div class="wp-block-group alignfull">
	<!-- wp:heading {"textAlign":"center"} -->
	<h2 class="wp-block-heading has-text-align-center">
		<?php echo esc_html_x( 'Ready to start?', 'Pattern heading', 'northwind' ); ?>
	</h2>
	<!-- /wp:heading -->

	<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
	<div class="wp-block-buttons">
		<!-- wp:button -->
		<div class="wp-block-button"><a class="wp-block-button__link wp-element-button">
			<?php echo esc_html_x( 'Get in touch', 'Pattern button', 'northwind' ); ?>
		</a></div>
		<!-- /wp:button -->
	</div>
	<!-- /wp:buttons -->
</div>
<!-- /wp:group -->

The header fields you will use most:

Header Meaning
Title Name shown in the inserter. Required.
Slug Unique name in the form theme-slug/pattern-name. Required.
Description Short text for screen readers and tooltips.
Categories One or more registered category slugs, comma separated.
Keywords Extra search words in the inserter.
Viewport Width Width in pixels used to render the preview.
Block Types Blocks for which this pattern is offered as a transform or placeholder choice.
Post Types Post types for which the pattern is offered when starting a new entry.
Template Types Templates for which the pattern is suggested.
Inserter Set to no to hide it from the inserter (useful for patterns used only inside templates).

Because the file is PHP, you can translate strings with the usual i18n functions and build asset URLs with get_theme_file_uri(). Escape everything you print, as you will practice in Escaping Output.

A template or template part can then include a pattern by slug, using the core/pattern block:

HTML
<!-- wp:pattern {"slug":"northwind/call-to-action"} /-->

This is how a footer part can reuse a pattern that editors also find in the inserter.

Registering patterns from PHP

You can also register a pattern in code, which is the only option for a plugin that ships patterns. Do it on the init hook with register_block_pattern().

PHP
add_action( 'init', function () {
	register_block_pattern_category( 'northwind-sections', array(
		'label' => __( 'Northwind sections', 'northwind' ),
	) );

	register_block_pattern( 'northwind/quote', array(
		'title'      => __( 'Large quote', 'northwind' ),
		'categories' => array( 'northwind-sections' ),
		'content'    => '<!-- wp:quote --><blockquote class="wp-block-quote">'
			. '<p>Good design is obvious.</p></blockquote><!-- /wp:quote -->',
	) );
} );

register_block_pattern_category() creates a category with a slug and a label; patterns then list that slug in categories. If a pattern names a category that does not exist, it still registers but shows up only under "All". Core already ships categories such as featured, text, banner and footer, and you can add your own.

Remember the hook model from Actions and Filters: registration is just a callback that runs at the right moment. The stand-in below mimics a pattern registry so you can see the rules: unique slugs, a theme/name format, categories that must be registered, and a lookup by category.

PHP A pattern registry stand-in

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The real registry also validates required keys and stores extra data such as keywords and block types, but the shape is the same: a keyed collection that the inserter reads.

Synced patterns and pattern overrides

Sometimes you want a block group to be the same everywhere, for example a legal notice that appears on fifty pages and must change in one place. That is a synced pattern (called a reusable block before WordPress 6.3). Authors create it in the editor with the "Create pattern" action and choose the synced option. WordPress stores it as a post of type wp_block, and each page holds only a reference:

HTML
<!-- wp:block {"ref":412} /-->

Edit pattern 412 and every page that references it updates. Registered theme patterns from files or PHP are not synced; only patterns saved by authors in the database can be.

A synced pattern has one limit: every copy is identical. Pattern overrides (added in WordPress 6.5) relax that. When you create a synced pattern you can mark individual blocks as overridable and give each a name. Each place that uses the pattern may then replace that block's content, for example a different heading in each use, while layout and styling stay synced. In the stored markup the override is expressed with block metadata:

HTML
<!-- wp:heading {"metadata":{"name":"Card title","bindings":{"__default":{"source":"core/pattern-overrides"}}}} -->
<h3 class="wp-block-heading">Default title</h3>
<!-- /wp:heading -->

Only some core blocks support overrides, namely Heading, Paragraph, Button and Image. The bindings entry is part of the wider block bindings system, which connects a block attribute to a data source such as post meta; overrides simply use a built-in source.

Overrides need a stored synced pattern. They are not available for patterns in your theme's patterns/ folder, because those are not synced.

Locking and starter patterns

When a pattern is a layout you want to protect, you can lock blocks so editors can change the text but not rip out the structure. A block-level lock is an attribute:

HTML
<!-- wp:group {"lock":{"move":true,"remove":true}} -->

move stops dragging the block elsewhere and remove stops deleting it. A container can also set templateLock (all, insert or contentOnly) to control its inner blocks; contentOnly is a popular choice because editors can edit text and images but not the layout. Locks guide editors; they are not a security measure, because anyone with the right capability can unlock blocks.

Starter patterns are patterns offered when an author creates a new page. A pattern that lists the right Post Types in its header can appear in the "Choose a pattern" modal, giving a new page a sensible first layout. Keep these few and well designed.

Choosing between a pattern and a template part

Use a template part for structure that is the same everywhere and editable in one place, like the header. Use a pattern for content layouts that authors will insert, copy and customize. Use a synced pattern when many pages must stay identical, and add overrides when only some text should vary. Remember that file-based patterns are loaded on demand and cached, so adding a file is enough; no registration code is required.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where does a block theme usually keep its file-based patterns?

    WordPress scans the theme's patterns/ directory and registers each file using the header comment for metadata.
  2. 2. What does the Slug header of a theme pattern look like?

    Pattern slugs are namespaced as theme-slug/pattern-name and must be unique.
  3. 3. What is the difference between a normal pattern and a synced pattern?

    Inserting a normal pattern copies its blocks. A synced pattern is a wp_block post that pages reference, so editing it updates every page.
  4. 4. Which feature lets each use of a synced pattern replace some text while keeping the layout synced?

    Pattern overrides, built on block bindings, let marked blocks differ per use while the rest stays synced.
  5. 5. Which hook is the right place to call register_block_pattern()?

    Registration belongs on init, the same hook used for post types, taxonomies and blocks.

Summary

  • A pattern is reusable block markup with metadata; inserting it copies the blocks into the page.
  • Block themes add patterns as PHP files in patterns/, with Title and Slug headers; plugins use register_block_pattern() on init.
  • Categories group patterns in the inserter; create your own with register_block_pattern_category().
  • Synced patterns are wp_block posts referenced by <!-- wp:block {"ref":ID} /-->; overrides allow per-use content for Heading, Paragraph, Button and Image.
  • Locking and contentOnly protect layout for editors, but are not security.
  • The registry TryIt is a stand-in; real WordPress has the same idea with more validation.

Next up: Style Variations, Fonts and Design Tokens.