How to create a default page template

Level: ,

Estimated reading time: 3 minutes

Updated June 28, 2022

When a user creates a new custom page template via the block editor, WordPress loads a default template with a few basic blocks. The purpose of this template is to make sure that the user is not met with a blank template. Some users can find the empty space overwhelming, and they don’t know where to start editing.
– Also, users might not know how to add the post content block to show their content in the template.

To create a new page template from the interface, open the selected post or page in the block editor. Then go to the Template section in the page sidebar and choose “New”:

The option to create new templates  is located below the template select list in the Template panel in the post settings sidebar.

The default template includes groups, site title, tagline, a separator block, the post title and post content. It does not include a site footer:

The default template in the template editor, which includes the post content block.

I strongly recommend replacing these blocks with a template that matches your theme. If you include a site header and site footer, the user can match their template with the rest of the site.

Filtering block_editor_settings_all

To change the block content of the template, you need to use the block_editor_settings_all filter. The setting that you are updating is called defaultBlockTemplate.

I recommend these two resources for learning more about the filter:

Block editor handbook reference

Creating an empty template

In some cases, you may prefer a blank template since you don’t need to remove any existing blocks when you open the template editor. In this case, just leave the setting empty:

function prefix_default_page_template( $settings ) {
	$settings['defaultBlockTemplate'] = "";
	return $settings;
}
add_filter( 'block_editor_settings_all', 'prefix_default_page_template' );

Using a file as the default template

You can add a template by including an HTML file with your block markup inside.
You could for example use your standard template for pages. In this code example, I created a custom template that I called default, and placed it in the templates folder:

function prefix_default_page_template( $settings ) {
	$settings['defaultBlockTemplate'] = file_get_contents( get_theme_file_path( 'templates/default.html' ) );
	return $settings;
}
add_filter( 'block_editor_settings_all', 'prefix_default_page_template' );

Using markup directly in the filter

Another option is to use block markup directly in the filter. This may be preferable if you only want to add a few blocks:

function prefix_default_page_template( $settings ) {
	$settings['defaultBlockTemplate'] = '<!-- wp:template-part {"slug":"header","theme":"theme-slug","tagName":"header"} /-->
<!-- wp:group {"tagName":"main","layout":{"inherit":true}} -->
<main class="wp-block-group">
<!-- wp:post-title /-->
<!-- wp:post-content {"align":"full","layout":{"inherit":true}} /--></main>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer","theme":"theme-slug","tagName":"footer"} /-->';
	return $settings;
}
add_filter( 'block_editor_settings_all', 'prefix_default_page_template' );

Troubleshooting template parts

If you test your default template and you notice an error message that says: “Template part has been deleted or is unavailable”, add the theme attribute to your template part block markup:

<!-- wp:template-part {"slug":"footer","theme":"theme-slug","tagName":"footer"} /-->

If your theme name is “fse”, the code would be:

<!-- wp:template-part {"slug":"footer","theme":"fse","tagName":"footer"} /-->