Reusable Block Patterns That Editors Actually Use

准备：Set Up a Safe 2026 Pattern Workspace

Work on WordPress 6.9 or later in 2026, PHP 8.2+, and a block theme such as Twenty Twenty-Five or your agency base theme. Use a staging clone with WP-CLI available, because pattern registration is code-driven and should never require manual database edits. Create a small mu-plugin or site-specific plugin instead of dropping experimental code into functions.php; this gives you a single switch for rollback and keeps patterns portable across theme swaps. If your team already maintains a design system, align spacing, colors, and typography with Building a Design System with theme.json Tokens before writing markup, because hardcoded hex values and random padding are the fastest way to make editors abandon patterns.

Create this structure:

wp-content/
  plugins/
    acme-editor-patterns/
      acme-editor-patterns.php
      patterns/
        hero-compact.php
        proof-strip.php
        faq-two-column.php
      assets/
        pattern-preview.png

Then scaffold and activate it:

mkdir -p wp-content/plugins/acme-editor-patterns/patterns
cd wp-content/plugins/acme-editor-patterns
touch acme-editor-patterns.php
wp plugin activate acme-editor-patterns --url=https://staging.example.test
wp option update blogname 'ACME Pattern Staging'

Add the plugin header and guard. This is the first copy-pasteable baseline; it registers a category and one pattern, escapes PHP output correctly, and uses content as validated block markup rather than raw shortcodes. Note the escaped angle brackets inside the code block.

<?php
/**
 * Plugin Name: ACME Editor Patterns
 * Description: Curated WordPress block patterns for editorial teams.
 * Version: 1.0.0
 * Requires at least: 6.9
 * Requires PHP: 8.2
 * Text Domain: acme-editor-patterns
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

add_action( 'init', 'acme_register_editor_pattern_assets', 20 );

function acme_register_editor_pattern_assets(): void {
    if ( ! function_exists( 'register_block_pattern' ) ) {
        return;
    }

    register_block_pattern_category(
        'acme-editor',
        array(
            'label'       => __( 'ACME Editor', 'acme-editor-patterns' ),
            'description' => __( 'Approved layouts for campaign and service pages.', 'acme-editor-patterns' ),
        )
    );

    register_block_pattern(
        'acme-editor/hero-compact',
        array(
            'title'       => __( 'Compact Hero with CTA', 'acme-editor-patterns' ),
            'description' => __( 'Short headline, supporting copy, and one primary button.', 'acme-editor-patterns' ),
            'categories'  => array( 'acme-editor', 'featured' ),
            'keywords'    => array( 'hero', 'cta', 'landing' ),
            'viewportWidth' => 900,
            'blockTypes'  => array( 'core/group' ),
            'content'     => '<!-- wp:group {"layout":{"type":"constrained"},"style":{"spacing":{"padding":{"top":"var:preset|spacing|50","bottom":"var:preset|spacing|50"}}} } --><div class="wp-block-group" style="padding-top:var:preset|spacing|50;padding-bottom:var:preset|spacing|50"><!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Add your headline</h1><!-- /wp:heading --><!-- wp:paragraph --><p>Add one sentence of context for the reader.</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">Get started</a></div><!-- /wp:button --></div><!-- /wp:buttons --></div><!-- /wp:group -->',
        )
    );
}

Why this preparation matters: registration runs on init, not on page load in the editor only. If you attach it to admin_init, REST pattern discovery and front-end block resolution can disagree. If you use theme.json preset slugs inside markup, editors inherit future design-token changes instead of inheriting your hardcoded 2026 guesses. Common pitfall: copying serialized block markup from a page that contains a plugin block you are not shipping. On staging it looks fine; on production the editor shows a “block has encountered an unexpected error” notice. Keep patterns to core blocks during the first pass.

Step / Process: Register, Categorize, Test, Ship, Roll Back

1. Prepare the plugin folder, activate it with WP-CLI, and confirm WordPress 6.9+ plus PHP 8.2+ on staging.
2. Register categories first, then call register_block_pattern() for each curated layout with stable namespaced IDs.
3. Validate block markup with parse_blocks(), open the inserter, and insert every pattern into a fresh draft.
4. Check editor search, category filters, responsive preview, and front-end rendering against theme.json tokens.
5. Deploy the plugin via your normal release process, clear object cache, and watch for registration warnings in debug.log.
6. Roll back by deactivating the plugin or reverting the release tag; never delete editor content to “remove” a registration.

register_block_pattern: The Registration Contract Editors Depend On

register_block_pattern() accepts a namespaced name such as acme-editor/hero-compact and an args array. As of WordPress 6.9 in 2026, the practical fields are title, description, categories, keywords, content, viewportWidth, blockTypes, postTypes, inserter, and source. Treat the name as an API: once editors build pages with it, renaming the ID does not rewrite existing inserted blocks, but it does break any documentation, block-type binding, and future unregister_block_pattern() calls. Use lowercase vendor prefixes, never dates, and never “v2” in the slug.

How to register from pattern files instead of one giant function

For more than three patterns, move each layout into patterns/*.php returning an array, then loop. WordPress also auto-discovers /patterns/*.php files in block themes, but an explicit plugin loop gives you version gates, capability checks, and a single rollback switch. Create patterns/proof-strip.php:

<?php
return array(
    'title'       => __( 'Proof Strip', 'acme-editor-patterns' ),
    'description' => __( 'Three metrics with short labels.', 'acme-editor-patterns' ),
    'categories'  => array( 'acme-editor' ),
    'keywords'    => array( 'stats', 'trust', 'metrics' ),
    'viewportWidth' => 1100,
    'content'     => '<!-- wp:group {"layout":{"type":"constrained"}} --><div class="wp-block-group"><!-- wp:columns {"align":"wide"} --><div class="wp-block-columns alignwide"><!-- wp:column --><div class="wp-block-column"><!-- wp:heading {"level":3} --><h3 class="wp-block-heading">120+</h3><!-- /wp:heading --><!-- wp:paragraph --><p>Launches</p><!-- /wp:paragraph --></div><!-- /wp:column --><!-- wp:column --><div class="wp-block-column"><!-- wp:heading {"level":3} --><h3 class="wp-block-heading">99.9%</h3><!-- /wp:heading --><!-- wp:paragraph --><p>Uptime</p><!-- /wp:paragraph --></div><!-- /wp:column --><!-- wp:column --><div class="wp-block-column"><!-- wp:heading {"level":3} --><h3 class="wp-block-heading">24h</h3><!-- /wp:heading --><!-- wp:paragraph --><p>Response</p><!-- /wp:paragraph --></div><!-- /wp:column --></div><!-- /wp:columns --></div><!-- /wp:group -->',
);

Now replace the single call in the main plugin with a loader. This also demonstrates a safe rollback helper and a debug-time validation check:

function acme_register_editor_pattern_assets(): void {
    if ( ! function_exists( 'register_block_pattern' ) ) {
        return;
    }

    register_block_pattern_category( 'acme-editor', array(
        'label' => __( 'ACME Editor', 'acme-editor-patterns' ),
    ) );

    $files = glob( __DIR__ . '/patterns/*.php' );
    foreach ( $files as $file ) {
        $args = require $file;
        $name = 'acme-editor/' . basename( $file, '.php' );

        if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
            $parsed = parse_blocks( $args['content'] ?? '' );
            if ( empty( $parsed ) || 'core/freeform' === ( $parsed[0]['blockName'] ?? '' ) ) {
                error_log( 'ACME pattern invalid markup: ' . $name );
                continue;
            }
        }

        $args['categories'] = array_merge(
            array( 'acme-editor' ),
            $args['categories'] ?? array()
        );

        register_block_pattern( $name, $args );
    }
}

// Emergency rollback: add ?acme_patterns_off=1 to any admin URL.
add_action( 'init', function (): void {
    if ( is_admin() && isset( $_GET['acme_patterns_off'] ) && current_user_can( 'manage_options' ) ) {
        remove_action( 'init', 'acme_register_editor_pattern_assets', 20 );
        unregister_block_pattern_category( 'acme-editor' );
    }
}, 5 );

How to verify registration

Run wp eval 'print_r( WP_Block_Patterns_Registry::get_instance()->get_all_registered() );' --url=https://staging.example.test | grep acme-editor. You should see each namespaced ID, its categories, and source marked as plugin. Then open /wp-admin/site-editor.php, create a draft page, press the inserter, and search “Proof Strip”. If the pattern appears but inserts an empty group, your block comment delimiters were mangled by a template literal or a visual editor copy; re-copy from the Block Editor code view, not from rendered HTML. Official reference: register_block_pattern() on developer.wordpress.org.

Common pitfalls and rollback

• Duplicate IDs: a theme /patterns/ file with the same header Slug: silently wins or triggers a doing_it_wrong notice. Prefix everything and grep with grep -R "Slug: acme-editor" wp-content/themes wp-content/plugins.
• Wrong hook priority: registering at init priority 1 can run before categories from other plugins. Priority 20 is a stable default.
• Missing translations: use __() with your text domain and run wp i18n make-pot . languages/acme-editor-patterns.pot.
• Rollback: wp plugin deactivate acme-editor-patterns --url=https://staging.example.test. Existing inserted blocks remain ordinary editable blocks; only future inserter availability disappears. That is the behavior you want.

Pattern Categories: Curate the Inserter Instead of Dumping 40 Layouts

Categories are the editor’s navigation. register_block_pattern_category() takes a slug and label plus optional description; every pattern then lists category slugs in categories. In 2026 the inserter still mixes core categories, theme categories, and plugin categories, so an agency site with “Featured”, “Text”, “Gallery”, “ACME Editor”, “Landing”, “SEO”, and “Old 2024” trains editors to ignore all of them. Ship three to five categories maximum: one vendor bucket, one task bucket, and optionally featured for the three layouts used weekly. If you need more, you have a template problem, not a category problem.

Step: build a category map and hide experimental patterns

Define the map in one place and set 'inserter' => false for patterns that are only referenced by blockTypes or by a template. This keeps the picker clean while still allowing contextual suggestions when an editor inserts a core/group or core/query block.

add_action( 'init', 'acme_register_pattern_categories', 10 );
function acme_register_pattern_categories(): void {
    $map = array(
        'acme-editor'  => __( 'ACME Editor', 'acme-editor-patterns' ),
        'acme-landing' => __( 'Campaign Sections', 'acme-editor-patterns' ),
        'acme-support' => __( 'Support Content', 'acme-editor-patterns' ),
    );
    foreach ( $map as $slug => $label ) {
        register_block_pattern_category( $slug, array( 'label' => $label ) );
    }
}

// In patterns/faq-two-column.php add:
// 'categories'  => array( 'acme-support' ),
// 'inserter'    => false,
// 'blockTypes'  => array( 'core/group' ),

Verify with wp eval 'print_r( WP_Block_Pattern_Categories_Registry::get_instance()->get_all_registered() );' | grep acme-, then ask a real editor to find “FAQ two column” without telling them the category name. If they scroll instead of search, add a keywords entry using their wording, not your component-library wording. For broader governance on who should own this kind of editorial infrastructure, our How to Vet a Professional WordPress Company in 2026 guide is a useful companion when you are handing the system to a client team.

Common pitfalls and rollback

Registering a category with a core slug such as text or featured does not create a new bucket; it merges your patterns into an already crowded one. Another frequent issue is registering categories after patterns at the same priority; the pattern still stores the slug, but the inserter label falls back or the tab disappears. Keep categories at priority 10 and patterns at 20. To roll back a bad taxonomy, call unregister_block_pattern_category( 'acme-landing' ) on init priority 30, redeploy, then remove the leftover slugs from the pattern arrays in the next release. Do not rename a category slug in place: editors’ muscle memory and any training screenshots break immediately.

Synced Patterns: Use Them for Global Fragments, Not for Layouts

Synced patterns (called reusable blocks before WordPress 6.3, still stored as the wp_block post type in 2026) are database content, not code. Editing one updates every instance site-wide. That is correct for a legal disclaimer, a campaign banner with an expiry date, or a contact CTA that marketing changes every Friday. It is wrong for a hero, a testimonial, or a pricing table where each page needs its own copy. When an editor inserts a registered WordPress block patterns entry, they get independent blocks; when they insert a synced pattern, they get a reference. Confusing those two is the most common production ticket we see.

Step: create, inspect, and convert safely

In the Block Editor, select a group, open the block options menu, choose Create pattern, name it Legal footer note, and enable Synced. Then inspect the row:

wp post list --post_type=wp_block --fields=ID,post_title,post_status,post_date --format=table
wp post get 184 --field=post_content | head -c 400
wp eval 'echo count( get_posts( array( "post_type" => "wp_block", "numberposts" => -1 ) ) );'

To convert a synced instance back to ordinary blocks, click the pattern toolbar and choose Detach (WordPress 6.9 labels it “Detach” in the pattern options panel). Verify by editing the text on one page and reloading another page that uses the same synced pattern: the other page must stay unchanged. To remove the global fragment entirely, delete the wp_block post only after detaching every instance, otherwise pages render an unresolved block reference. Use wp post delete 184 --force on staging first and grep content: wp search-replace 'wp:block {"ref":184}' '' wp_posts --dry-run.

Common pitfalls and rollback

• Content in database, not Git: synced patterns do not travel with a plugin deploy. Include them in your migration checklist or recreate them with wp_insert_post( array( 'post_type' => 'wp_block', ... ) ) in an idempotent deploy script.
• Capability surprise: editors who can edit pages may not be able to edit the shared wp_block. Grant edit_posts scoped access deliberately or route changes through a content owner.
• Cache: a persistent object cache can serve an old wp_block revision for minutes. Run wp cache flush after a synced edit and verify in a private window.
• Rollback: restore the wp_block row from your pre-deploy wp db export --add-drop-table snapshot, then wp cache flush. Never roll back by editing each page manually.

If a client needs code-owned layouts plus a handful of globally managed fragments, that split is usually part of a wider build spec; our Custom WordPress Development team documents both layers in the handover so editors know which switch to touch.

Patterns vs Templates: Put Structure in Templates, Sections in Patterns

Templates define the document: templates/page.html, templates/single.html, templates/archive.html, and parts/header.html in a block theme. They own wp:template-part, wp:post-content, query loops, and the overall hierarchy resolved by the template hierarchy. Patterns define a repeatable section that an editor drops inside post-content. A pattern can be referenced from a template via <!-- wp:pattern {"slug":"acme-editor/hero-compact"} -->, but that turns an editor choice into a locked default; use it only for a starter skeleton that editors are expected to detach or replace.

Concern	Template	Pattern
File path	themes/acme/templates/page.html	plugins/acme-editor-patterns/patterns/*.php or theme /patterns/
Who edits it	Developer in Git, or Site Editor template mode	Editor in the page inserter
Scope	Whole document / archive / header	One section inside content
Change impact	All pages using that template	Only the inserted instance, unless synced
Rollback	Revert theme file or template revision	Deactivate plugin; existing content stays

Step: wire a template without hijacking editor control

Keep page.html minimal and let the pattern be a suggestion, not a cage:

<!-- wp:template-part {"slug":"header","area":"header"} /-->
<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
  <!-- wp:post-title {"level":1} /-->
  <!-- wp:post-content {"layout":{"type":"constrained"}} /-->
</main>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer","area":"footer"} /-->

Verify with wp eval 'echo locate_block_template( get_stylesheet_directory() . "/templates/page.html", "page", array() );' and by opening a new page: the title must come from the template, while the inserter still offers “Compact Hero with CTA”. If the hero appears automatically on every page, you pasted wp:pattern into the template; remove it. Official background: block theme templates on developer.wordpress.org. For more implementation notes, browse the technical column index.

Common pitfalls and rollback

Theme /patterns/*.php auto-registration and plugin registration can both fire, producing duplicate inserter cards with different IDs. Pick one owner per site. Another trap is putting postTypes on a pattern when the real constraint belongs in a template: 'postTypes' => array( 'page' ) hides a section from posts, but it does not give posts a different header. Roll back a template mistake with git revert <sha> && wp theme activate acme --url=https://staging.example.test, then clear the Site Editor template revision by restoring the saved wp_template post from the export taken before the change. Remember that Site Editor saves templates as database posts; reverting the file alone will not override a customized template row until you reset that customization.

验证：A Production-Ready Acceptance Test

Run this on staging before every release. First, wp plugin activate acme-editor-patterns and wp cache flush. Second, confirm registry output contains exactly the expected IDs with wp eval '$r=WP_Block_Patterns_Registry::get_instance(); foreach($r->get_all_registered() as $p){ if(str_starts_with($p["name"],"acme-editor/")) echo $p["name"].PHP_EOL; }'. Third, create a draft with wp post create --post_type=page --post_status=draft --post_title='Pattern QA 2026', insert each pattern in the browser, replace every placeholder string, and save. Fourth, render it with wp eval 'echo apply_filters("the_content", get_post(211)->post_content);' | grep -E 'wp-block-group|wp-block-columns' and check that no core/freeform, core/missing, or unresolved wp:block reference appears. Fifth, switch to a 380px viewport in browser dev tools and confirm columns stack via core layout rules rather than custom CSS. Sixth, deactivate the plugin, reload the saved draft, and confirm the content is still intact and editable. That last check is the single best signal that you shipped patterns rather than hidden dependencies.

Log the result in wp-content/debug.log with WP_DEBUG_LOG enabled, then turn WP_DEBUG off before production. If your release pipeline includes content governance, coordinate the pattern names with the team handling Choosing a Vendor for Core Content About WordPress SEO so heading levels and internal-link slots stay consistent across editorial templates.

回滚: Recover Cleanly When a Pattern Release Misbehaves

Rollback has three layers and you should execute them in order. Code layer: wp plugin deactivate acme-editor-patterns --url=https://example.com or redeploy the previous Git tag with git checkout v1.0.0 && wp plugin activate acme-editor-patterns. This removes inserter entries and category tabs within one request; it does not touch saved pages. Database layer: if the release also created synced patterns, restore only the wp_block rows from the pre-deploy dump using wp db import backup-pre-patterns.sql --skip-themes --skip-plugins on staging, verify, then repeat on production during a maintenance window. Avoid a full database restore for a single bad fragment. Template layer: reset customized wp_template posts in Site Editor or restore their revisions, because a file revert alone loses to a saved customization. Finally run wp cache flush, wp rewrite flush --hard, and re-run the six-step acceptance test above. Document the incident with the pattern ID, the WordPress version (6.9.x in 2026), the PHP version, and the exact block delimiter that failed; that note prevents the same malformed comment from returning in the next sprint.

Frequently asked questions

Do WordPress block patterns store content in the database?

Registered patterns live in code and only appear in the inserter. Once inserted, their blocks are saved inside that page’s post_content. Synced patterns are the exception: they are wp_block posts and pages store a ref to them.

Can I unregister a core or theme pattern in 2026?

Yes. Call unregister_block_pattern( 'core/query-standard-posts' ) or the theme slug on init priority 30, after the source registered it. Verify with the registry eval command; do not edit core files or theme /patterns/ files directly.

Should I use theme /patterns files or a plugin?

Use a plugin when patterns must survive a theme change, need version gates, or are shared across a multisite. Use theme /patterns/ files only for layouts tightly coupled to that theme’s theme.json and templates. Never register the same slug in both.

Action Checklist

• Create the acme-editor-patterns plugin on staging with WordPress 6.9+, PHP 8.2+, and WP-CLI available.
• Register 3–5 categories at init priority 10, then 6–12 namespaced patterns at priority 20 using core blocks and theme.json tokens.
• Run the six-step acceptance test, including the deactivation check that proves saved pages remain editable.
• Reserve synced wp_block entries for genuinely global fragments and include them in your database backup plan.
• Keep templates in templates/*.html, patterns inside post-content, and record the rollback tag before deploy.

Need a second pair of eyes on your editor system? Our engineers audit pattern registries, template hierarchy, and rollback plans for agency sites. Review the development service or see all services.

References & further reading

• WordPress Developer Documentation
• WordPress Theme Handbook
• WordPress Plugin Handbook