What are block patterns in WordPress and how to use them?

Block patterns are ready-made arrangements of blocks, such as a hero section, a pricing table, or a team grid, that you can insert into any post or page with one click and then customize. To use one, open the block inserter (the + button), switch to the Patterns tab, browse or search for a layout, and click it to add it to your content. You then replace the placeholder text and images with your own.

Patterns are one of the biggest time-savers in modern WordPress. Instead of building every section from scratch, you start from a professionally designed layout and adapt it. This guide explains what block patterns are, the different types, where they come from, how to use them in posts and in the Site Editor, how to create your own, and how developers can register patterns in a theme or plugin.

What Are Block Patterns?

A block pattern is a predefined collection of blocks saved together as a reusable design. A pattern might contain a Cover block with a heading and button, a set of Columns with images and text, or a full page layout with several sections.

When you insert a pattern, WordPress adds all of its blocks to your content. From that point on, they're regular blocks. You can edit the text, swap images, change colors, remove blocks, or rearrange them.

Block patterns were introduced in WordPress 5.5 and have grown steadily since. Today they're central to how block themes work, how the Site Editor builds templates, and how users design pages without code.

Patterns vs. Blocks

• A block is a single content element, like a Paragraph, Image, or Button.
• A pattern is a combination of blocks arranged into a useful layout.

Think of blocks as bricks and patterns as prebuilt walls.

Types of Block Patterns

Since WordPress 6.3, patterns come in a few flavors.

Unsynced Patterns

These are the standard patterns. When you insert one, you get an independent copy. Editing it in one post doesn't affect any other post or the original pattern. Most theme patterns and patterns from the Pattern Directory are unsynced.

Synced Patterns

Formerly called reusable blocks, synced patterns share a single source of content. Edit one instance, and every instance updates. They're ideal for calls-to-action, disclaimers, and other content that must stay identical everywhere. We cover them in detail in our guide to creating reusable blocks.

Theme and Plugin Patterns

Themes and plugins can register their own patterns in code. Block themes often include dozens, covering headers, footers, hero sections, testimonials, and full page layouts. These appear in the inserter automatically when the theme or plugin is active.

Template Part and Page Patterns

In the Site Editor, some patterns are associated with specific areas, such as headers or footers, and are offered when you replace a template part. WordPress can also show starter page patterns when you create a new page, giving you a full layout to begin from.

Where Block Patterns Come From

The patterns available on your site come from several sources:

• WordPress core: A small set of default patterns ships with WordPress.
• Your active theme: Block themes like Twenty Twenty-Four and Twenty Twenty-Five include many patterns designed to match the theme's style.
• Plugins: Plugins such as WooCommerce register patterns for product grids, featured products, and more.
• The WordPress Pattern Directory: A public library at wordpress.org/patterns with community-contributed patterns. Some themes load patterns from the directory automatically.
• You: Any pattern you create in the editor.

How to Use Block Patterns in a Post or Page

Inserting a pattern is simple.

1. Open the editor: Create or edit a post or page.
2. Open the block inserter: Click the blue + button (Toggle block inserter) in the top toolbar.
3. Select the Patterns tab: You'll see patterns organized by category, such as Featured, Banners, Call to Action, Gallery, Text, and more.
4. Browse or search: Click a category to preview its patterns, or type a keyword like "pricing" or "testimonial" into the search field.
5. Insert the pattern: Click the preview. The pattern is added where your cursor was.
6. Customize it: Click into each block to replace the text, upload your own images, update links, and adjust colors or spacing in the block settings sidebar.

You can also insert patterns through the inline inserter: click the small + that appears between blocks, then click Browse all and switch to Patterns.

Tip: Use the Pattern Explorer

For a larger view, click Explore all patterns (or the expand icon) at the bottom of the Patterns tab. It opens a full-screen modal that makes it easier to compare designs.

Replacing Placeholder Images

Most patterns include placeholder images. Select an image, click Replace in the toolbar, and choose an image from your media library or upload a new one. For Cover blocks, you can replace the background the same way.

How to Use Patterns in the Site Editor

If you use a block theme, patterns are just as useful for designing templates.

1. Open the Site Editor: Go to Appearance > Editor.
2. Choose what to edit: Select Templates to edit a template, such as the blog home or single post template, or Patterns to manage patterns and template parts.
3. Insert patterns into templates: Open a template, click the + inserter, and add patterns just as you would in a post.
4. Replace template parts: Select a header or footer, open the three-dot options menu, and choose Replace. WordPress shows header or footer patterns you can swap in.

The Patterns section of the Site Editor lists all patterns on your site, grouped into categories, with separate entries for your own patterns and theme patterns.

How to Create Your Own Block Pattern

You don't need code to create a pattern.

1. Design the layout: In any post, build the section you want to save. Wrap multiple blocks in a Group block so they save as one unit.
2. Select the group: Click the Group block so its toolbar appears.
3. Open the Options menu: Click the three dots in the toolbar.
4. Choose Create pattern.
5. Name it: Use a clear, descriptive name, like "Services: Three Columns".
6. Assign categories: Pick existing categories or type a new one.
7. Choose synced or unsynced: Turn the Synced toggle off if you want a reusable layout; leave it on for shared content.
8. Click Add.

Your pattern is now available under My patterns in the inserter and in the Site Editor's pattern library.

You can also create patterns from Appearance > Editor > Patterns by clicking the + (Add New) button and choosing Add new pattern.

How to Register Block Patterns in a Theme or Plugin

Developers can ship patterns with a theme or plugin so they're available on every site that uses it. There are two main approaches.

Method 1: Pattern Files in a Block Theme

For block themes (and classic themes since WordPress 6.0), the easiest method is to add PHP files to a /patterns folder in the theme root. WordPress automatically registers each file using the header comments.

Create patterns/hero-with-button.php:

<?php
/**
 * Title: Hero With Button
 * Slug: mytheme/hero-with-button
 * Categories: banner, featured
 * Keywords: hero, header, intro
 * Viewport Width: 1200
 * Description: A full-width cover section with a heading, text, and a button.
 */
?>
<!-- wp:cover {"dimRatio":60,"overlayColor":"contrast","minHeight":480,"align":"full","layout":{"type":"constrained"}} -->
<div class="wp-block-cover alignfull" style="min-height:480px"><span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim-60 has-background-dim"></span><div class="wp-block-cover__inner-container">
<!-- wp:heading {"textAlign":"center","level":1} -->
<h1 class="wp-block-heading has-text-align-center"><?php echo esc_html__( 'Build something great', 'mytheme' ); ?></h1>
<!-- /wp:heading -->
<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center"><?php echo esc_html__( 'A short sentence that explains what you offer and why it matters.', 'mytheme' ); ?></p>
<!-- /wp:paragraph -->
<!-- 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" href="/contact/"><?php echo esc_html__( 'Get in touch', 'mytheme' ); ?></a></div>
<!-- /wp:button -->
</div>
<!-- /wp:buttons -->
</div></div>
<!-- /wp:cover -->

The easiest way to get valid block markup is to build the layout in the editor, open the three-dot menu at the top right, switch to Code editor, and copy the markup. Then wrap translatable strings with functions like esc_html__().

Useful header fields include:

• Title and Slug (required): The slug should be namespaced, such as mytheme/hero-with-button.
• Categories: Comma-separated category slugs.
• Keywords: Extra search terms.
• Block Types: Associates the pattern with a block, such as core/template-part/header, so it's suggested when replacing headers.
• Post Types: Limits the pattern to certain post types.
• Inserter: Set to no to hide it from the inserter while keeping it available in templates.

Method 2: register_block_pattern() in PHP

In a plugin or classic theme, you can register patterns with register_block_pattern() on the init hook:

function sajjad_register_patterns() {
    register_block_pattern_category(
        'sajjad-marketing',
        array( 'label' => __( 'Marketing', 'sajjad' ) )
    );

    register_block_pattern(
        'sajjad/simple-cta',
        array(
            'title'       => __( 'Simple Call to Action', 'sajjad' ),
            'description' => __( 'A heading, a sentence, and a button.', 'sajjad' ),
            'categories'  => array( 'sajjad-marketing', 'call-to-action' ),
            'keywords'    => array( 'cta', 'button' ),
            'content'     => '<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group"><!-- wp:heading -->
<h2 class="wp-block-heading">' . esc_html__( 'Want to learn more?', 'sajjad' ) . '</h2>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p>' . esc_html__( 'Join our newsletter for practical WordPress tips.', 'sajjad' ) . '</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="/newsletter/">' . esc_html__( 'Subscribe', 'sajjad' ) . '</a></div>
<!-- /wp:button --></div>
<!-- /wp:buttons --></div>
<!-- /wp:group -->',
        )
    );
}
add_action( 'init', 'sajjad_register_patterns' );

Removing Core or Remote Patterns

If you want full control over which patterns appear, you can remove WordPress's default patterns and stop loading patterns from the remote Pattern Directory:

function sajjad_remove_default_patterns() {
    remove_theme_support( 'core-block-patterns' );
}
add_action( 'after_setup_theme', 'sajjad_remove_default_patterns' );

add_filter( 'should_load_remote_block_patterns', '__return_false' );

To remove a single pattern, use unregister_block_pattern( 'namespace/pattern-slug' ); on the init hook with a later priority than the one that registered it.

Loading Patterns From the Pattern Directory in theme.json

Block themes can pull specific patterns from the WordPress Pattern Directory by listing their slugs in theme.json:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "patterns": [ "short-text-surrounded-by-round-images", "partner-logos" ]
}

The slugs come from the pattern URLs on wordpress.org/patterns.

Best Practices for Using Block Patterns

• Start with your theme's patterns: They're designed to match your theme's fonts, colors, and spacing.
• Keep patterns flexible: Use theme colors and spacing presets instead of hard-coded values so patterns adapt when styles change.
• Replace all placeholders: Check every heading, image, link, and alt text before publishing.
• Build a small personal library: Save the sections you use often, like service lists or FAQ layouts.
• Name and categorize clearly: Future you will thank you when there are 50 patterns to search through.
• Check mobile layouts: Preview on mobile, since columns stack and spacing can change.
• Don't overload pages: A page stuffed with heavy patterns can become slow and cluttered. Use what supports your content.

Troubleshooting Block Patterns

I can't see the Patterns tab: Make sure you're using the block editor, not the Classic Editor plugin.

A theme pattern disappeared after switching themes: Theme patterns only exist while the theme is active. Content you already inserted remains, because it was copied into your post as regular blocks.

Registered pattern isn't showing: Check that the slug is unique and namespaced, the file is in the /patterns folder, the header comment is valid, and there are no PHP errors. Also check the Inserter and Post Types headers.

Pattern looks different than the preview: Patterns inherit your theme's styles. If you've customized global styles, the result may differ slightly from the preview in the directory.

---

FAQ: WordPress Block Patterns

---

Conclusion

Block patterns turn the WordPress block editor into a fast, flexible design tool. Instead of assembling every section block by block, you can insert a polished layout from your theme, a plugin, or the Pattern Directory, then make it your own. Unsynced patterns give you reusable starting points, while synced patterns keep shared content consistent across your site.

Start by exploring the patterns your theme already includes, then save the layouts you use most as your own patterns. If you build themes or plugins, registering patterns in the /patterns folder or with register_block_pattern() is one of the most helpful things you can do for your users. Either way, patterns will help you build better-looking pages in far less time.