register_block_template() │ WP 6.7.0

Registers a block page template for a theme.

The template becomes available in the Site Editor and can be used in the WordPress template hierarchy or selected for individual posts.

The theme and user customizations can override its content.

Templates should be registered on the init action.

The function registers full wp_template templates only. It does not support wp_template_part template parts.

Use unregister_block_template() when you need to remove a template registered by a plugin.

Uses: WP_Block_Templates_Registry::register()

No Hooks.

Returns

WP_Block_Template|WP_Error.

  • WP_Block_Template — the registered template object.
  • WP_Error — if the name has an invalid format, contains uppercase letters, or a template with that name is already registered.

Usage

register_block_template( $template_name, $args );
$template_name(string) (required)

The template name in the plugin-slug//template-name format.

Both parts can contain only lowercase Latin letters, numbers, hyphens, and underscores: a-z 0-9 _ -.

$args(array)

Template settings.

  • title(string)
    The template name in the Site Editor and other interface elements.
    Default: the $template_name value

  • description(string)
    The template description in the Site Editor.
    Default: ''

  • content(string)
    The template's source content in block markup format. Used when displaying and editing the template.
    Default: ''

  • post_types(string[])
    A list of post types for which the template can be selected.
    Default: []

  • plugin(string)
    The slug of the plugin that registered the template.
    The value is not used in the current implementation. The slug is determined from the first part of $template_name.

Default: []

Examples

#1 Register a template for the book post type

The template will appear among the available templates for book posts.

add_action( 'init', 'my_plugin_register_book_template' );

function my_plugin_register_book_template() {
	register_block_template(
		'my-plugin//book-layout',
		[
			'title'       => __( 'Book layout', 'my-plugin' ),
			'description' => __( 'Template for displaying a book.', 'my-plugin' ),
			'content'     => '
				<!-- 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-featured-image /-->
					<!-- wp:post-content /-->
				</main>
				<!-- /wp:group -->
				<!-- wp:template-part {"slug":"footer","area":"footer"} /-->
			',
			'post_types'  => [ 'book' ],
		]
	);
}

Changelog

Since 6.7.0 Introduced.

register_block_template() code WP 7.1.2

wp-includes/block-template.php 
function register_block_template( $template_name, $args = array() ) {
	return WP_Block_Templates_Registry::get_instance()->register( $template_name, $args );
}

Gutenberg (blocks editor)

FSE (block theme)