WordPress Block Pattern Example: Register Reusable Editorial Layouts

Last reviewed: April 21, 2026

Block patterns are one of the simplest ways to give editors consistent layouts without building a custom block for every design. A pattern inserts prebuilt block markup into the editor. After insertion, the content becomes normal editable blocks.

This article shows how to register a custom block pattern from a plugin, when patterns are better than blocks, and how to keep the pattern useful without locking content into a fragile layout.

When to use this

Use a block pattern for reusable editorial layouts: callout sections, comparison rows, author boxes, lead magnets, content disclaimers, feature summaries, or documentation intros. Use a custom block instead when the component needs custom controls, dynamic rendering, server data, or strict validation.

Register a pattern category

<?php
/**
 * Plugin Name: VulnWP Editorial Patterns
 * Description: Registers custom editor block patterns.
 * Version: 1.0.0
 */

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

add_action( 'init', 'vulnwp_register_editorial_patterns' );

function vulnwp_register_editorial_patterns() {
	register_block_pattern_category(
		'vulnwp-editorial',
		array(
			'label' => __( 'VulnWP Editorial', 'vulnwp-patterns' ),
		)
	);

	register_block_pattern(
		'vulnwp/security-callout',
		array(
			'title'       => __( 'Security callout', 'vulnwp-patterns' ),
			'description' => _x( 'A heading, paragraph, and checklist for security notes.', 'Block pattern description', 'vulnwp-patterns' ),
			'categories'  => array( 'vulnwp-editorial' ),
			'keywords'    => array( 'security', 'callout', 'checklist' ),
			'content'     => '<!-- wp:group {\"className\":\"vulnwp-security-callout\"} -->
<div class=\"wp-block-group vulnwp-security-callout\">
<!-- wp:heading {\"level\":3} -->
<h3>' . esc_html__( 'Before you deploy', 'vulnwp-patterns' ) . '</h3>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p>' . esc_html__( 'Review access, backups, monitoring, and rollback before shipping this change.', 'vulnwp-patterns' ) . '</p>
<!-- /wp:paragraph -->
</div>
<!-- /wp:group -->',
		)
	);
}

Pattern or reusable block?

A block pattern is copied into the post. Editing one inserted pattern does not update every other post. That is good for editorial flexibility. If you need one central source of truth, use a synced pattern, reusable block, or dynamic block depending on the workflow.

Plugin PHP vs theme pattern files

Block themes can auto-register pattern files from a /patterns directory. Plugins often use register_block_pattern() because the pattern belongs to plugin functionality or should survive theme changes. Choose the location based on ownership: visual theme pattern, or reusable product/editorial feature.

If a pattern is tied to a site’s active visual identity, theme ownership is reasonable. If it supports a plugin workflow, plugin ownership is safer.

Keep pattern content clean

The content value is block markup. Keep it readable, avoid unnecessary inline styles, and use classes that your theme or plugin can style predictably. Do not paste giant generated layouts full of fragile attributes unless you are prepared to maintain them.

Testing workflow

1. Confirm the pattern appears in the intended category.
2. Insert it into a draft post and edit every piece of text.
3. Switch to mobile preview and check spacing.
4. Deactivate the plugin on staging and confirm existing post content remains usable.
5. Test with the site’s active theme and at least one fallback theme.

Production checklist

• Register patterns on init.
• Use a namespaced pattern name.
• Provide a useful title, description, category, and keywords.
• Keep markup simple enough for editors to understand after insertion.
• Do not use patterns for dynamic data that should update centrally.
• Test the pattern in the editor, frontend, and mobile preview.

Common mistakes

• Using patterns for application logic. Patterns are editorial templates, not dynamic components.
• No category. Editors cannot find patterns easily.
• Overly complex markup. Fragile patterns become hard to edit.
• Forgetting translations. Pattern titles and descriptions should be translation-ready.
• Assuming updates are global. Inserted pattern content is normal post content.

Related reading

For dynamic editor components, read the block.json custom block example. For translation rules, pair this with the internationalization example.

References and further reading

• WordPress Block Editor Handbook: Block Patterns
• WordPress Code Reference: register_block_pattern()
• WordPress Code Reference: register_block_pattern_category()