Block Patterns - Gutenberg

Block Patterns are predefined block layouts available from the patterns tab of the block inserter. Once inserted, blocks are ready for additional content and configuration.

What are Block Patterns?

Patterns provide:

Reusable layouts: Pre-configured combinations of blocks
Quick starting points: Jump-start content creation with templates
Design consistency: Ensure layouts match your design system
User productivity: Speed up common content creation tasks

Registering Block Patterns

PHP Registration

Use register_block_pattern() to register a pattern:

register_block_pattern(
	'my-plugin/call-to-action',
	array(
		'title'       => __( 'Call to Action', 'my-plugin' ),
		'description' => __( 'A bold call-to-action with button', 'my-plugin' ),
		'content'     => '<!-- wp:group {"backgroundColor":"primary"} -->
			<div class="wp-block-group has-primary-background-color has-background">
				<!-- wp:heading -->
				<h2>Ready to get started?</h2>
				<!-- /wp:heading -->
				
				<!-- wp:paragraph -->
				<p>Join thousands of users today.</p>
				<!-- /wp:paragraph -->
				
				<!-- wp:button -->
				<div class="wp-block-button">
					<a class="wp-block-button__link">Sign Up Now</a>
				</div>
				<!-- /wp:button -->
			</div>
			<!-- /wp:group -->',
		'categories'  => array( 'call-to-action' ),
	)
);

Call register_block_pattern() from a handler attached to the init hook.

function my_plugin_register_patterns() {
	register_block_pattern( ... );
}
add_action( 'init', 'my_plugin_register_patterns' );

Pattern Properties

Required Properties

title (required)

Human-readable title displayed in the pattern inserter.

'title' => __( 'Two Column Layout', 'my-plugin' )

content (required)

Block HTML markup for the pattern. This is the serialized block format.

'content' => '<!-- wp:columns -->
<div class="wp-block-columns">...</div>
<!-- /wp:columns -->'

Optional Properties

description

A visually hidden text used to describe the pattern in the inserter. Helps users discover patterns while searching.

'description' => __( 'A two-column layout with an image and text', 'my-plugin' )

keywords

Array of aliases or keywords that help users discover the pattern while searching.

'keywords' => array( 'cta', 'action', 'button', 'hero' )

viewportWidth

Intended width of the pattern for a scaled preview in the inserter.

'viewportWidth' => 1200

blockTypes

Array of block types the pattern is intended for. Makes the pattern available in block transforms.

'blockTypes' => array( 'core/paragraph' )

postTypes

Restrict the pattern to specific post types.

'postTypes' => array( 'post', 'page' )

templateTypes

Array of template types where the pattern is relevant.

'templateTypes' => array( '404', 'single-post', 'page' )

inserter

Control visibility in the inserter. Set to false to hide the pattern (for programmatic use only).

'inserter' => false

source

Denotes the source of the pattern.

// For plugins
'source' => 'plugin'

// For themes
'source' => 'theme'

Complete Pattern Example

<?php
function my_plugin_register_patterns() {
	register_block_pattern(
		'my-plugin/feature-section',
		array(
			'title'         => __( 'Feature Section', 'my-plugin' ),
			'description'   => __( 'A three-column feature section with icons and descriptions', 'my-plugin' ),
			'categories'    => array( 'featured' ),
			'keywords'      => array( 'features', 'services', 'columns' ),
			'viewportWidth' => 1280,
			'content'       => '
				<!-- wp:heading {"textAlign":"center"} -->
				<h2 class="has-text-align-center">Our Features</h2>
				<!-- /wp:heading -->

				<!-- wp:columns -->
				<div class="wp-block-columns">
					<!-- wp:column -->
					<div class="wp-block-column">
						<!-- wp:heading {"level":3} -->
						<h3>Fast</h3>
						<!-- /wp:heading -->
						
						<!-- wp:paragraph -->
						<p>Lightning-fast performance for your users.</p>
						<!-- /wp:paragraph -->
					</div>
					<!-- /wp:column -->

					<!-- wp:column -->
					<div class="wp-block-column">
						<!-- wp:heading {"level":3} -->
						<h3>Secure</h3>
						<!-- /wp:heading -->
						
						<!-- wp:paragraph -->
						<p>Built with security best practices in mind.</p>
						<!-- /wp:paragraph -->
					</div>
					<!-- /wp:column -->

					<!-- wp:column -->
					<div class="wp-block-column">
						<!-- wp:heading {"level":3} -->
						<h3>Scalable</h3>
						<!-- /wp:heading -->
						
						<!-- wp:paragraph -->
						<p>Grows with your business needs.</p>
						<!-- /wp:paragraph -->
					</div>
					<!-- /wp:column -->
				</div>
				<!-- /wp:columns -->
			',
		)
	);
}
add_action( 'init', 'my_plugin_register_patterns' );

Pattern Categories

Group patterns into categories for better organization.

Registering Pattern Categories

register_block_pattern_category(
	'my-plugin-layouts',
	array( 'label' => __( 'My Plugin Layouts', 'my-plugin' ) )
);

The category won’t show in the Patterns panel unless at least one pattern is assigned to it.

Complete Category Example

<?php
function my_plugin_register_pattern_categories() {
	// Register categories
	register_block_pattern_category(
		'my-plugin-hero',
		array( 'label' => __( 'Hero Sections', 'my-plugin' ) )
	);

	register_block_pattern_category(
		'my-plugin-cta',
		array( 'label' => __( 'Call to Action', 'my-plugin' ) )
	);
}
add_action( 'init', 'my_plugin_register_pattern_categories' );

Unregistering Categories

unregister_block_pattern_category( 'my-plugin-layouts' );

Unregistering Block Patterns

Remove previously registered patterns:

unregister_block_pattern( 'my-plugin/call-to-action' );

Call unregister_block_pattern() from a handler attached to the init hook.

function my_plugin_unregister_patterns() {
	unregister_block_pattern( 'my-plugin/old-pattern' );
}
add_action( 'init', 'my_plugin_unregister_patterns' );

Contextual Block Patterns

Patterns can be attached to specific block types, making them available as transforms.

register_block_pattern(
	'my-plugin/styled-paragraph',
	array(
		'title'      => __( 'Styled Paragraph', 'my-plugin' ),
		'blockTypes' => array( 'core/paragraph' ),
		'content'    => '
			<!-- wp:paragraph {"backgroundColor":"primary","textColor":"white"} -->
			<p class="has-white-color has-primary-background-color has-text-color has-background">
				Styled paragraph text
			</p>
			<!-- /wp:paragraph -->
		',
	)
);

When a user selects a paragraph block, this pattern appears in the transform menu.

Multi-Block Patterns

Patterns can transform multiple selected blocks:

register_block_pattern(
	'my-plugin/heading-with-paragraph',
	array(
		'title'      => __( 'Heading with Paragraph', 'my-plugin' ),
		'blockTypes' => array( 'core/paragraph', 'core/heading' ),
		'content'    => '
			<!-- wp:group -->
			<div class="wp-block-group">
				<!-- wp:heading {"fontSize":"large"} -->
				<h2 class="has-large-font-size">Heading Text</h2>
				<!-- /wp:heading -->
				
				<!-- wp:paragraph -->
				<p>Paragraph text</p>
				<!-- /wp:paragraph -->
			</div>
			<!-- /wp:group -->
		',
	)
);

If the user selects both a paragraph and heading, this pattern becomes available.

Semantic Block Patterns

In block themes, mark patterns as “header” or “footer” (template part areas):

register_block_pattern(
	'my-plugin/site-header',
	array(
		'title'      => __( 'Site Header', 'my-plugin' ),
		'categories' => array( 'header' ),
		'blockTypes' => array( 'core/template-part/header' ),
		'content'    => '
			<!-- wp:group -->
			<div class="wp-block-group">
				<!-- wp:site-logo /-->
				<!-- wp:navigation /-->
			</div>
			<!-- /wp:group -->
		',
	)
);

These patterns appear when inserting or replacing header/footer template parts.

Common Pattern Examples

Hero Section

register_block_pattern(
	'my-plugin/hero',
	array(
		'title'      => __( 'Hero Section', 'my-plugin' ),
		'categories' => array( 'featured' ),
		'content'    => '
			<!-- wp:cover {"url":"https://example.com/hero.jpg","minHeight":500} -->
			<div class="wp-block-cover" style="min-height:500px">
				<div class="wp-block-cover__inner-container">
					<!-- wp:heading {"level":1,"fontSize":"huge"} -->
					<h1 class="has-huge-font-size">Welcome to Our Site</h1>
					<!-- /wp:heading -->
					
					<!-- wp:paragraph {"fontSize":"large"} -->
					<p class="has-large-font-size">Start your journey here</p>
					<!-- /wp:paragraph -->
					
					<!-- wp:buttons -->
					<div class="wp-block-buttons">
						<!-- wp:button -->
						<div class="wp-block-button">
							<a class="wp-block-button__link">Learn More</a>
						</div>
						<!-- /wp:button -->
					</div>
					<!-- /wp:buttons -->
				</div>
			</div>
			<!-- /wp:cover -->
		',
	)
);

Testimonial

register_block_pattern(
	'my-plugin/testimonial',
	array(
		'title'      => __( 'Testimonial', 'my-plugin' ),
		'categories' => array( 'text' ),
		'content'    => '
			<!-- wp:group {"style":{"spacing":{"padding":{"top":"2rem","right":"2rem","bottom":"2rem","left":"2rem"}}}} -->
			<div class="wp-block-group" style="padding-top:2rem;padding-right:2rem;padding-bottom:2rem;padding-left:2rem">
				<!-- wp:quote -->
				<blockquote class="wp-block-quote">
					<p>This product changed my life!</p>
					<cite>Jane Doe</cite>
				</blockquote>
				<!-- /wp:quote -->
			</div>
			<!-- /wp:group -->
		',
	)
);

Pricing Table

register_block_pattern(
	'my-plugin/pricing-table',
	array(
		'title'         => __( 'Pricing Table', 'my-plugin' ),
		'categories'    => array( 'featured' ),
		'viewportWidth' => 1200,
		'content'       => '
			<!-- wp:columns -->
			<div class="wp-block-columns">
				<!-- wp:column -->
				<div class="wp-block-column">
					<!-- wp:heading {"textAlign":"center","level":3} -->
					<h3 class="has-text-align-center">Basic</h3>
					<!-- /wp:heading -->
					
					<!-- wp:paragraph {"align":"center","fontSize":"large"} -->
					<p class="has-text-align-center has-large-font-size">$9/mo</p>
					<!-- /wp:paragraph -->
					
					<!-- wp:list -->
					<ul><li>Feature 1</li><li>Feature 2</li><li>Feature 3</li></ul>
					<!-- /wp:list -->
					
					<!-- wp:button {"align":"center"} -->
					<div class="wp-block-button aligncenter">
						<a class="wp-block-button__link">Choose Plan</a>
					</div>
					<!-- /wp:button -->
				</div>
				<!-- /wp:column -->
				
				<!-- wp:column -->
				<div class="wp-block-column">
					<!-- wp:heading {"textAlign":"center","level":3} -->
					<h3 class="has-text-align-center">Pro</h3>
					<!-- /wp:heading -->
					
					<!-- wp:paragraph {"align":"center","fontSize":"large"} -->
					<p class="has-text-align-center has-large-font-size">$29/mo</p>
					<!-- /wp:paragraph -->
					
					<!-- wp:list -->
					<ul><li>Feature 1</li><li>Feature 2</li><li>Feature 3</li><li>Feature 4</li></ul>
					<!-- /wp:list -->
					
					<!-- wp:button {"align":"center"} -->
					<div class="wp-block-button aligncenter">
						<a class="wp-block-button__link">Choose Plan</a>
					</div>
					<!-- /wp:button -->
				</div>
				<!-- /wp:column -->
			</div>
			<!-- /wp:columns -->
		',
	)
);

Creating Pattern Content

To generate the block HTML markup for patterns:

Method 1: Copy from the Editor

Create the layout in the editor

Build your pattern layout using the block editor.

Copy to clipboard

Select all blocks (Cmd/Ctrl + A) and copy them.

View as HTML

Click the three dots menu → “Copy all blocks” or use Code Editor view to see the HTML.

Paste into your pattern

Paste the HTML markup into the content field.

Method 2: Export from the Editor

Use the Pattern export feature (if available in your WordPress version) to export patterns created in the editor.

Best Practices

Provide clear titles and descriptions: Help users understand when to use each pattern
Use appropriate categories: Make patterns easy to discover
Add keywords: Include search terms users might use
Set viewport width: Ensure patterns display correctly in preview
Use placeholder content: Make it obvious what content should be replaced
Test across themes: Ensure patterns work with different themes
Consider accessibility: Use semantic HTML and proper heading hierarchy
Keep patterns focused: Each pattern should serve a specific purpose

Pattern vs Reusable Block

Feature	Block Pattern	Reusable Block
Editable after insert	Yes	Synced across all instances
When to use	Starting point templates	Truly reusable content
Updates	Independent	Updates everywhere
Content	Placeholder text	Actual content

Use patterns for layout templates. Use reusable blocks for repeated actual content.

Block Variations - Different configurations of a single block
Block Templates - Default block layouts for post types
Block Transforms - Convert between block types

Get Started

Development Environment

Core Concepts

Block Development

Data & State

Guides

​What are Block Patterns?

​Registering Block Patterns

​PHP Registration

​Pattern Properties

​Required Properties

​title (required)

​content (required)

​Optional Properties

​description

​categories

​keywords

​viewportWidth

​blockTypes

​postTypes

​templateTypes

​inserter

​source

​Complete Pattern Example

​Pattern Categories

​Registering Pattern Categories

​Complete Category Example

​Unregistering Categories

​Unregistering Block Patterns

​Contextual Block Patterns

​Multi-Block Patterns

​Semantic Block Patterns

​Common Pattern Examples

​Hero Section

​Testimonial

​Pricing Table

​Creating Pattern Content

​Method 1: Copy from the Editor

​Method 2: Export from the Editor

​Best Practices

​Pattern vs Reusable Block

​Related Documentation

Build docs developers (and LLMs) love

What are Block Patterns?

Registering Block Patterns

PHP Registration

Pattern Properties

Required Properties

title (required)

content (required)

Optional Properties

description

categories

keywords

viewportWidth

blockTypes

postTypes

templateTypes

inserter

source

Complete Pattern Example

Pattern Categories

Registering Pattern Categories

Complete Category Example

Unregistering Categories

Unregistering Block Patterns

Contextual Block Patterns

Multi-Block Patterns

Semantic Block Patterns

Common Pattern Examples

Hero Section

Testimonial

Pricing Table

Creating Pattern Content

Method 1: Copy from the Editor

Method 2: Export from the Editor

Best Practices

Pattern vs Reusable Block

Related Documentation