register_block_pattern() │ WP 5.5.0

Registers a new block pattern for the block editor (Gutenberg).

Allows creating block patterns that can be quickly inserted into content through the editor interface. This simplifies the creation of repeating structures, such as sections with buttons, galleries, or columns.

The function should be called on the init hook.

You can limit the availability of the template for certain post types using the postTypes parameter.

Default patterns are registered by the _register_core_block_patterns_and_categories() function and are located in the core folder /wp-includes/block-patterns/. For example: /wp-includes/block-patterns/query-grid-posts.php.

If you have disabled support for standard WordPress templates via remove_theme_support( 'core-block-patterns' ), make sure you have registered at least one category of templates; otherwise, the editor may not function correctly.

Use register_block_pattern_category() to register a category for patterns.

No Hooks.

Returns

true|false.

  • true - if the template is successfully registered.
  • false - in case of an error.

Usage

register_block_pattern( $pattern_name, $pattern_properties );
$pattern_name(string) (required)
Unique name of the pattern, including the namespace (for example, my-plugin/hero-section).
$pattern_properties(array) (required)

Associative array with template parameters:

  • title (string) (required) — Readable name of the template.
  • content (string) (required) — HTML code of the blocks that make up the template.
  • description (string) — Description of the template for the insertion panel.
  • categories (array) — Array of categories to which the template belongs.
  • keywords (array) — Keywords for searching the template.

  • viewportWidth (int) — Width of the template preview in pixels.

  • blockTypes (array) — Array of blocks associated with the template.
    Specifies which blocks the pattern is related to and limits its display only in those blocks. For example, if you specify 'blockTypes' => [ 'core/columns' ], the template will be available only when adding the "Columns" block.

    This is convenient when the template logically relates to a specific block and should not be used separately. It simplifies working with the editor — the user sees only those templates that are suitable for the current context.

  • postTypes (array) — Array of post types for which the template is available.

  • templateTypes (array) — Array of template types in which the template is applied.
    The templateTypes parameter indicates in which site templates (for example, page, single) the block pattern will be available. This works in the Site Editor and allows showing the block pattern only in the necessary contexts, for example, only for pages or posts. It simplifies the interface and makes block patterns more targeted.

  • inserter (bool) — Determines whether the block pattern will be displayed in the editor's insertion panel.

    false — the template will not appear in the list available for insertion through the editor interface. This is useful when you want to use the block pattern only programmatically or automatically (for example, when creating posts or templates), but do not want the user to insert it manually.
    true — (default) the template will be available for insertion through the editor interface.

  • source (string) — Source of the template (plugin or theme).

See the list of all parameters in WP_Block_Patterns_Registry::register().

Examples

0

#1 Registration of a simple template with two buttons

Creates a template with two horizontal buttons: one filled, the other with a border.

add_action( 'init', 'my_plugin_register_block_patterns' );

function my_plugin_register_block_patterns() {
	register_block_pattern(
		'my-plugin/two-buttons',
		array(
			'title'       => __( 'Two Buttons', 'my-plugin' ),
			'description' => _x( 'Two horizontal buttons: left filled, right with a border.', 'Block pattern description', 'my-plugin' ),
			'categories'  => array( 'buttons' ),
			'content'     => '<!-- wp:buttons {"align":"center"} -->
<div class="wp-block-buttons aligncenter">
	<!-- wp:button {"backgroundColor":"primary","borderRadius":0} -->
	<div class="wp-block-button"><a class="wp-block-button__link has-background has-primary-background-color no-border-radius">Button 1</a></div>
	<!-- /wp:button -->

	<!-- wp:button {"textColor":"primary","borderRadius":0,"className":"is-style-outline"} -->
	<div class="wp-block-button is-style-outline"><a class="wp-block-button__link has-text-color has-primary-color no-border-radius">Button 2</a></div>
	<!-- /wp:button -->
</div>
<!-- /wp:buttons -->',
		)
	);
}
0

#2 Registration of a template from an external file

Loads the content of the template from an external PHP file.

add_action( 'init', 'my_plugin_register_external_pattern' );
function my_plugin_register_external_pattern() {
	ob_start();
	include plugin_dir_path( __FILE__ ) . 'patterns/hero-section.php';
	$pattern_content = ob_get_clean();

	register_block_pattern(
		'my-plugin/hero-section',
		array(
			'title'      => __( 'Hero section', 'my-plugin' ),
			'categories' => array( 'hero' ),
			'content'    => $pattern_content,
		)
	);
}

Changelog

Since 5.5.0 Introduced.

register_block_pattern() code WP 6.8.1

wp-includes/class-wp-block-patterns-registry.php 
function register_block_pattern( $pattern_name, $pattern_properties ) {
	return WP_Block_Patterns_Registry::get_instance()->register( $pattern_name, $pattern_properties );
}

Gutenberg (blocks editor)

Block Editor (Gutenberg)