WordPress Block Patterns: What They Are and How to Use Them
What WordPress block patterns are, synced vs unsynced, overrides, the 7.0 content-only change, and how to register patterns in a theme or plugin.

WordPress block patterns are ready-made groups of blocks, such as a hero section, a pricing table or a signup box, that you insert from the block inserter and then edit like any other content. There are two kinds you create yourself: unsynced patterns, which paste an independent copy each time, and synced patterns (the old reusable blocks), where one edit updates every place the pattern is used. Themes and plugins add more patterns from PHP, and thousands of free ones live in the WordPress Pattern Directory.
That is the short version. The rest of this guide covers how to use patterns in the editor today, what changed in WordPress 7.0 (inserted patterns now open in a content-only mode, which surprises a lot of people), how to register your own with a /patterns folder or register_block_pattern(), and the mistakes we see most often. Our team checked every function, file header and menu path against the WordPress 7.1.4 source and the official handbooks on 18 November 2026, and ran the code samples on a clean 7.1.4 install with Twenty Twenty-Five.
This page has no recorded Search Console queries yet, so the headings follow the questions people ask when they first meet patterns in the block editor.
What is a block pattern in WordPress?
A pattern is saved block markup with a name. When you insert it, WordPress drops those blocks into your post, page or template. Patterns arrived in WordPress 5.5 in August 2020, and since then they have become the main way themes ship layouts.
Patterns come from five places, and knowing which one you are looking at explains most of their behaviour:
Source | Who creates it | Where it is stored | Editable from the dashboard? |
|---|---|---|---|
Your own patterns (synced or unsynced) | Site users, in the editor | The database, as the | Yes |
Theme patterns | The theme author | PHP files in the theme’s | No, but you can duplicate them |
Plugin patterns | Plugin authors | PHP, through | No |
Core patterns | WordPress itself | Files in | No |
Pattern Directory patterns | The community, on WordPress.org | Fetched from the WordPress.org API | No, copy to use |
On a fresh 7.1.4 install, WordPress registers 21 pattern categories in wp-includes/block-patterns.php, from Banners and Call to action to Testimonials, Gallery and Media, plus a small set of its own query and navigation overlay patterns. A block theme such as Twenty Twenty-Five adds its own; it ships 98 pattern files.
What is the difference between synced and unsynced patterns?
Synced patterns stay linked to one source. Unsynced patterns are copied in and forget where they came from. That single difference decides which one you want.
Unsynced pattern | Synced pattern | |
|---|---|---|
What gets inserted | A copy of the blocks | A reference to one saved pattern |
Edit one instance | Only that copy changes | Every instance changes, site-wide |
Good for | Starting layouts you will customise per page | Content that must stay identical: a disclaimer, a signup box, opening hours |
Old name | None (these were always “patterns”) | Reusable blocks, renamed in WordPress 6.3 |
Per-instance content | Everything, it is a copy | Only blocks with overrides enabled (since 6.6) |
Under the hood both are stored as wp_block posts. WordPress 6.3 added the wp_pattern_sync_status post meta so a saved pattern can be marked unsynced; without that meta value, a pattern is synced. The WordPress.org documentation on patterns still explains synced patterns under the old reusable blocks address, which tells you how direct the rename was.
What are pattern overrides?
Overrides fill the gap between the two types. Shipped in WordPress 6.6, they let a synced pattern keep its layout locked while chosen blocks hold different content in each place it is used. Picture a team member card: the design is synced across the site, but the name, photo and role change per person.
- Create a synced pattern and click Edit original.
- Select a block that supports overrides, such as a Heading, Paragraph, Image or Button.
- In the block sidebar, open Advanced and click Enable overrides.
- Give it a unique name, for example “Member name”, and save the pattern.
Each instance of that pattern can now change those named blocks while the rest stays synced. The list of supported blocks comes from the block bindings API; in WordPress 7.1.4 core’s list covers Paragraph, Heading, List Item, Image and Button among others. The WordPress Developer Blog introduction to overrides walks through the same steps with screenshots.
How do I insert a block pattern?
- Open a post, page or template in the editor.
- Click the + (Block Inserter) button in the top toolbar.
- Switch to the Patterns tab.
- Pick a category, or type in the search box. The My patterns category holds the ones you created.
- Click a pattern to insert it, or drag it into place.
Two shortcuts help. Type / in an empty paragraph and start typing a pattern name. And when you create a new page on a block theme, WordPress may show a “Choose a pattern” window first; those are starter patterns registered for the Post Content block, explained in the developer section below.
If your theme offers a whole page layout as a pattern, our guide to switching a pattern into your home page covers the template side of that job.
Why can I not edit a pattern after inserting it in WordPress 7.0?
Because WordPress 7.0, released in May 2026, changed how inserted patterns behave. An unsynced pattern now opens in content-only mode: you can change text and images straight away, but layout, block structure and style controls are locked until you click Edit pattern (or double-click the pattern). The block also shows the pattern icon, which used to appear only on synced patterns.
The pattern is still unsynced. Nothing links it to other copies; the extra step is there to stop people breaking a designed section by accident. The official Pattern editing in WordPress 7.0 dev note describes the change, and adds that synced patterns now open their original in an isolated editor through Edit original, with a way back to the page you came from.
If your editors find the new step slows them down, the same dev note documents a switch. This snippet restores the old behaviour for unsynced patterns; we confirmed the setting is applied in the editor settings on 7.1.4:
// Checked on 18 November 2026 on WordPress 7.1.4.
add_filter( 'block_editor_settings_all', function ( $settings ) {
$settings['disableContentOnlyForUnsyncedPatterns'] = true;
return $settings;
} );We would leave the default on for most client sites. It is exactly the protection non-technical editors need, and the “Edit pattern” button is one click away.
How do I create my own pattern in the editor?
No code is needed for this.
- Build the section in a post or page: for example a Group block with a heading, a paragraph and a button.
- Select the outer block (a Group makes this easy) or several blocks at once.
- Open the block toolbar’s options menu (the three dots) and choose Create pattern.
- Name it, pick or type a category, and decide on the Synced toggle: on for a synced pattern, off for an unsynced one.
- Click Add. The pattern now appears under My patterns in the inserter.
Wrapping the section in one Group block first keeps the pattern tidy and easy to select later. Our explainer on the Group block shows why it is the usual outer container for patterns.
Where do I manage saved patterns?
It depends on the theme type, and we read this straight from wp-admin/menu.php in 7.1.4:
Your theme | Menu path |
|---|---|
Block theme | Appearance > Editor > Patterns |
Classic theme with | Appearance > Design > Patterns |
Other classic themes | Appearance > Patterns |
From that screen you can rename, duplicate, delete and categorise patterns, and export a pattern as a JSON file to import on another site. Theme patterns show there too, but you cannot edit them in place; duplicate one to get an editable copy of your own.
Where can I find more block patterns?
The official WordPress Pattern Directory holds free, community-made patterns, moderated by volunteers. Browse by category, open a pattern, click Copy pattern, then paste it into the editor. Because a copied pattern is just block markup, it inserts as normal blocks with no plugin needed. Replace any placeholder images with your own media afterwards.
WordPress also loads some directory patterns into the inserter automatically, as long as the theme keeps core pattern support and nothing turns off remote loading. Block themes can request specific directory patterns by slug in the patterns key of theme.json; core then fetches and registers them, which you can see in _register_remote_theme_patterns().
Beyond that, many block themes and block plugins ship their own pattern libraries. A theme’s patterns go with the theme, so switching themes can leave pages using its pattern markup without its styles. That is fine for plain core blocks and messy for blocks from a plugin you later remove.
How do I register a block pattern in a theme?
Since WordPress 6.0, a theme only needs to drop PHP files into a /patterns folder. WordPress reads a comment header at the top of each file and registers it on init; no function call needed. Here is a complete file we tested in a Twenty Twenty-Five child theme:
<?php
// Saved as patterns/newsletter-cta.php in the child theme. Checked on 18 November 2026, WordPress 7.1.4.
/**
* Title: Newsletter call to action
* Slug: twp-child/newsletter-cta
* Categories: call-to-action, twp-marketing
* Keywords: newsletter, signup, email
* Description: A short signup prompt with a heading, a line of text and a button.
* Viewport Width: 1200
* Block Types: core/post-content
* Post Types: page
* Inserter: yes
*/
?>
<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
<!-- wp:heading -->
<h2 class="wp-block-heading"><?php echo esc_html_x( 'Get one WordPress tip a week', 'Pattern heading', 'twp-child' ); ?></h2>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p><?php echo esc_html_x( 'Short, tested, no spam.', 'Pattern text', 'twp-child' ); ?></p>
<!-- /wp:paragraph -->
<!-- wp:buttons -->
<div class="wp-block-buttons"><!-- wp:button -->
<div class="wp-block-button"><a class="wp-block-button__link wp-element-button" href="/subscribe/"><?php echo esc_html_x( 'Subscribe', 'Pattern button', 'twp-child' ); ?></a></div>
<!-- /wp:button --></div>
<!-- /wp:buttons -->
</div>
<!-- /wp:group -->The headers WordPress reads are defined in WP_Theme::get_block_patterns(). Title and Slug are required; a file missing either is skipped with a “doing it wrong” notice.
Header | Required | What it does |
|---|---|---|
Title | Yes | Name shown in the inserter; translated with the theme text domain |
Slug | Yes | Unique id, usually |
Categories | No | Comma-separated category slugs |
Keywords | No | Extra search terms |
Description | No | Hidden text for screen readers and search |
Viewport Width | No | Width used for the preview thumbnail |
Block Types | No | Blocks this pattern suits; |
Post Types | No | Limits the pattern to these post types |
Template Types | No | Templates it suits, such as |
Inserter | No |
|
Because the file is PHP, you can translate strings and build URLs with functions such as esc_html_x() and get_theme_file_uri(), which a static HTML pattern cannot do. Child theme patterns with the same slug win over the parent’s, so a child theme can replace one parent pattern without touching the rest. The Theme Handbook chapter on patterns has more examples.
Why does my new pattern file not show up?
Since WordPress 6.4, core caches the list of theme pattern files, and since 6.6 that cache is a site transient whatever the environment. A brand new file may stay invisible until the cache expires or is cleared. During development, set the development mode so WordPress skips the cache:
// wp-config.php, development sites only. Checked on 18 November 2026.
define( 'WP_DEVELOPMENT_MODE', 'theme' );Remove it before launch. On a live site, switching themes and back, or a deploy routine that calls wp_get_theme()->delete_pattern_cache(), clears the cached list.
How do I register a pattern from a plugin?
Plugins, and themes that prefer code, call register_block_pattern() on the init hook. It takes a name and an array with the same fields as the file headers, in camelCase, plus content holding the block markup:
// Checked on 18 November 2026 on WordPress 7.1.4.
add_action( 'init', 'twp_register_php_pattern' );
function twp_register_php_pattern() {
register_block_pattern(
'twp-child/notice-box',
array(
'title' => __( 'Notice box', 'twp-child' ),
'description' => __( 'A highlighted note with a heading and one paragraph.', 'twp-child' ),
'categories' => array( 'text' ),
'keywords' => array( 'note', 'alert' ),
'content' => '<!-- wp:group {"style":{"spacing":{"padding":{"top":"var:preset|spacing|30","bottom":"var:preset|spacing|30","left":"var:preset|spacing|30","right":"var:preset|spacing|30"}}},"backgroundColor":"accent-5","layout":{"type":"constrained"}} --><div class="wp-block-group has-accent-5-background-color has-background" style="padding-top:var(--wp--preset--spacing--30);padding-right:var(--wp--preset--spacing--30);padding-bottom:var(--wp--preset--spacing--30);padding-left:var(--wp--preset--spacing--30)"><!-- wp:heading {"level":3} --><h3 class="wp-block-heading">Before you start</h3><!-- /wp:heading --><!-- wp:paragraph --><p>Back up the site first.</p><!-- /wp:paragraph --></div><!-- /wp:group -->',
)
);
}Two tips. Build the layout in the editor first, then copy the markup from the Code editor view so it is valid. And prefix the name with your plugin or theme slug, since the registry is shared by everything on the site. To remove a pattern registered by something else, call unregister_block_pattern( 'name' ) on init at a later priority than the original registration.
How do I add a custom pattern category?
Register it with register_block_pattern_category() before or alongside your patterns, then reference its slug:
// Checked on 18 November 2026 on WordPress 7.1.4.
add_action( 'init', 'twp_register_pattern_category' );
function twp_register_pattern_category() {
register_block_pattern_category(
'twp-marketing',
array(
'label' => __( 'Marketing', 'twp-child' ),
'description' => __( 'Signup and promo sections.', 'twp-child' ),
)
);
}A pattern that names an unregistered category still registers, but it will not appear under a category of that name in the inserter. Our newsletter pattern above uses both a core category (call-to-action) and this custom one, and showed up under both in our test.
How do I remove core and Pattern Directory patterns?
Client sites often want only the patterns the theme designer made. Two lines handle it:
// Checked on 18 November 2026 on WordPress 7.1.4.
add_action( 'after_setup_theme', function () {
remove_theme_support( 'core-block-patterns' );
} );
add_filter( 'should_load_remote_block_patterns', '__return_false' );The first stops WordPress registering its bundled patterns and featured directory patterns. The second stops all requests to the Pattern Directory, including any slugs listed in theme.json. In our test the core query patterns disappeared and only the theme’s own patterns remained. Your saved patterns in the database are not affected.
Which kind of pattern should I use?
You want to | Use |
|---|---|
Reuse a layout and change it each time | An unsynced pattern |
Show identical content everywhere and edit it once | A synced pattern |
Keep a design fixed but vary a few texts or images | A synced pattern with overrides |
Ship layouts with a theme | Files in the |
Ship layouts with a plugin |
|
Offer layouts for new pages | A pattern with Block Types set to |
Patterns also suit content work, not only design. Our post on using block patterns for blog monetization shows how a saved call-to-action or affiliate box keeps posts consistent.
Common mistakes people report
We collected these from WordPress.org forum threads, GitHub issues and the core dev notes, and read each one on 18 November 2026.
- Thinking an unsynced pattern became synced after updating to 7.0. A July 2026 forum thread shows the confusion: the pattern icon and the Edit pattern step made unsynced patterns look synced. They are not; it is the new content-only mode, which a filter can switch off.
- New pattern files that never appear. Theme developers in an August 2024 thread only saw new files after enabling theme development mode, and an October 2026 Studio issue reports the same cache problem in a local development tool. The pattern cache is the cause.
- Directory patterns missing inside templates. A Gutenberg issue from July 2024 reports that Pattern Directory patterns referenced in a template may not render, for example when that template was already customised and saved in the database. Use theme pattern files for anything a template depends on.
- Authors unable to detach a synced pattern. Until a Gutenberg change merged in October 2026, the Detach option only showed for users allowed to edit the synced pattern, so authors could not turn an admin-made pattern into a local copy. Check your Gutenberg or core version before assuming it is a permissions bug.
- Editing a synced pattern and changing every page. This is how synced patterns are meant to work, and it is the reason the overrides feature exists, as the original pattern overrides tracking issue explains. Detach first if you only want to change one page.
- Leaving out the Slug or Title header. WordPress skips the file and only logs a notice when debugging is on, so the pattern silently goes missing. Both headers are required in 7.1.4.
Frequently asked questions
Are block patterns the same as templates?
No. A template controls the layout of a whole type of page, such as every single post. A pattern is a section you insert into a page or a template. Templates often contain patterns.
Do block patterns slow down my site?
Not on the front end: an inserted pattern is ordinary block markup, the same as if you had built it by hand. Hundreds of registered patterns can make the inserter slower to open in the editor, which is one reason to remove core and directory patterns you never use.
Can I use patterns with a classic theme?
Yes. Patterns work in the block editor whatever the theme type. Classic themes reach the pattern manager through Appearance > Patterns or Appearance > Design, as shown in the table above.
What happens to my patterns if I change themes?
Patterns you saved yourself stay, because they live in the database. Patterns the old theme registered disappear from the inserter, but content you already inserted stays on your pages as normal blocks.
Can I move synced patterns to another site?
Yes. Export each one as JSON from the Patterns screen (the Export as JSON action) and bring it in on the other site with Import pattern from JSON, found under the add new pattern button on the Patterns screen.
Are Pattern Directory patterns free to use on client sites?
Yes. The directory’s About page says people can use submitted patterns without cost or attribution, and submitters must hold the rights to what they upload. Swap any sample images for media you have the rights to.
Patterns are also the quickest route to consistent sections in WooCommerce block themes, where the Single Product template itself is built from blocks; our guide to changing product page tab titles shows that template in practice.
Plugins we build and run
We maintain these ourselves, which is why we can support them on your site.
- BuddyNextThe self-hosted community engine for WordPress
- BuddyXFree community theme, Pro when you outgrow it
- ReignPremium community theme. Add pieces, build anything
- JetonomyCommunity forum and Q&A for WordPress
- EventonomyEvents and RSVPs for WordPress communities
- LearnomyCourses and learning communities on WordPress
- ListoraDirectories and listings your members can browse
- SnipShareCode sharing built for developer communities
- WB Ad ManagerAd placements that turn traffic into revenue
- WP Career BoardA job board your community actually uses
- WP Sell ServicesSell services with offers, orders, and payouts
- MediaVersePhotos, video, and media albums for members
- WB GamificationPoints, badges, and rewards that keep members active
- Product RoadmapPublic roadmaps with voting your users trust


