WordPress Block Patterns

What a block pattern is: a saved arrangement of blocks that WordPress inserts as an independent copy. Choose a pattern from the inserter, and the blocks land in your content exactly as designed — then behave like anything else you built by hand. Edit one instance and nothing else on the site changes, because after insertion the pattern's job is finished.

Copy versus reference is the whole distinction

Three things look similar in the inserter and behave completely differently once used:

• A pattern is a copy. Inserting it clones a block arrangement into the post. The original definition and the inserted copy have no ongoing connection.
• A synced pattern (the renamed reusable block) is a reference. Every insertion points at the same stored content, so editing one instance edits every instance, everywhere it appears.
• A template or template part is structural. It wraps content rather than sitting inside it — a header or footer used by every page that template applies to, edited in the site editor rather than inserted into a post.

Confusing a pattern with a synced pattern is the single most common support question in this area: someone inserts what they assume is an independent copy, edits it on one page, and watches the same edit appear — or fail to appear — elsewhere. The icon in the inserter distinguishes the two, but it is easy to miss, and both categories are often shown in the same panel.

Where patterns come from

Three sources feed the pattern inserter, and they stack rather than replace each other:

Switching themes changes which theme-supplied patterns show up in the inserter, which is one more reason a pattern already inserted into a page keeps working after a theme change even though its source entry disappears — the copy already exists in the post content, independent of whatever offered it originally.

Creating one

The editor turns any existing selection of blocks into a pattern without touching code: select the blocks, open the block toolbar's options menu, and save the selection as a pattern. That stores it as a wp_block post behind the scenes — the same post type synced patterns use, with a flag marking it unsynced. Categorise it well; the inserter's search is the only way anyone finds a pattern again once the list grows past a handful.

For anything meant to ship with a theme or plugin rather than live in one site's database, register it in PHP instead:

register_block_pattern('sitename/callout-banner', [
    'title'       => __('Callout banner', 'sitename'),
    'description' => __('Full-width text with a button.', 'sitename'),
    'categories'  => ['sitename'],
    'content'     => '<!-- wp:group {"align":"full"} -->...<!-- /wp:group -->',
]);

The content value is block markup — the same HTML comments the editor writes — not a template file, so building it usually means designing the layout in the editor, copying the block markup from the code editor view, and pasting it into the PHP string.

The pattern directory and why remote patterns are slow

Beyond core and the active theme, WordPress can fetch community-submitted patterns from wordpress.org's pattern directory directly inside the inserter. That request happens over the network at the moment someone opens the inserter, which is why remote patterns sometimes load visibly slower than local ones, or fail to appear at all on a host that blocks outbound requests. None of that affects a pattern once it has been inserted — the copy that lands in the post is self-contained — but it does mean the browsing experience depends on wordpress.org being reachable from wherever WordPress runs its requests. A site with strict egress rules, or a staging environment without outbound access, will show a thin pattern list even though the theme registers plenty locally.

Registering patterns in a theme

A block theme can ship its own patterns as PHP files under a patterns directory rather than calling register_block_pattern directly. Each file carries a header comment with the pattern's title, slug and category, followed by the block markup, and WordPress scans the directory and registers every file it finds. A child theme can use the same mechanism to add a patterns directory of its own, supplementing the parent's patterns without editing parent files — which keeps the addition intact through parent theme updates.

When a pattern is the wrong tool

A pattern is the wrong tool when content needs to change everywhere at once — that is what a synced pattern is for. It is also the wrong tool for structural chrome every page must share, such as a header, which a site editor template part handles more reliably, or for a dynamically updating list of posts, which calls for the Query Loop block instead. And a pattern is a poor substitute for a proper layout tool when the goal is a fully custom page design outside the editor's block model entirely; that territory belongs to a dedicated page builder.

Common mistakes

• Assuming a pattern updates everywhere. It does not. That behaviour belongs to synced patterns, not regular ones.
• Editing the source and expecting existing pages to change. Once inserted, a pattern copy is independent of its origin, including a theme update that changes the registered version.
• Registering many patterns from functions.php. A dedicated patterns directory, per how functions.php works, keeps registration organised and avoids one enormous file.
• Blaming a slow inserter on the site itself. Sluggish loading in the pattern browser is often the remote directory request, not local performance.
• Building single-use layouts as patterns. If it is only ever used once, it does not need a pattern; build it directly in the page.

Verify

Insert a pattern, edit the copy on the page, then reload the pattern inserter and confirm the original entry is unchanged — that confirms it behaved as a copy rather than a reference. If a theme registers patterns via a patterns directory, deactivate the theme and check the inserter no longer lists them, confirming registration is tied to the active theme rather than leaking globally. On a slow-loading inserter, check the browser's network panel for a request to the pattern directory API; a stalled or failed request there, not local performance, is the usual cause.