How to add default blocks to the block editor

Level: ,

In this short lesson, I will explain how to add default blocks to any post type. This feature is independent of the theme templates because it adds blocks to the content, directly in the block editor. This lesson is an updated rewrite of two previous lessons.

Estimated reading time: 3 minutes

I have found three reliable ways to add content directly in the block editor:

  • Adding blocks when registering a custom post type
  • Updating the post type object of any post type
  • Using the default_content filter.

Using register_post_type() to add default blocks to custom post types

Plugins use register_post_type() to extend WordPress with custom post types.

I am going to assume that you are familiar with the concept and show you a short code example.

The template argument in register_post_type() is optional and it accepts blocks and block settings in the form of a nested array:

function myplugin_register_book_post_type() {
    $args = array(
        'public' => true,
        'label'  => 'Books',
        'show_in_rest' => true,
        'template' => array(
            array( 'core/columns', array(), array(
                array( 'core/column', array(), array(
                    array( 'core/image', array() ),
                ) ),
                array( 'core/column', array(), array(
                    array( 'core/paragraph', array(
                        'placeholder' => 'Add a inner paragraph'
                    ) ),
                ) ),
            ) )
    register_post_type( 'book', $args );
add_action( 'init', 'myplugin_register_book_post_type' );

Implementation and troubleshooting tips

The array structure is the same as for a parsed block. The block name is a string, while the attributes and the inner blocks are arrays. One trick you can use to get the correct format is to add your blocks to the block editor, copy the markup, and run it through parse_blocks().
Print the result of parse_blocks() and compare the array with your template.

array ( 
    0 => array ( 
        'blockName' => 'core/paragraph', 
        'attrs' => array ( 
            'textColor' => 'vivid-red', 
            'backgroundColor' => 'luminous-vivid-amber',

Adding a block template by updating the post type object

The first example showed how to add default blocks when registering a new custom post type. You can also update the template argument of an existing post type. In this example, the post type is “book”:

function myplugin_register_template() {
    $post_type_object = get_post_type_object( 'book' );
    $post_type_object->template = array(
        array( 'core/image' ),
add_action( 'init', 'myplugin_register_template' );

Adding default blocks with the default_content filter

Another way to display default blocks in the editor is to filter the default content.
If you find the format with the nested arrays complicated, then using this filter may be a better option because it uses regular block markup.

You can read about the default_content filter in the WordPress code reference:

In this code example, I am first checking if the post type is book, before adding the block markup to the $content variable. I am adding the same content as in the previous example, a columns block with an image and a paragraph:

function prefix_filter_book_content( $content, $post ) {
	if ( $post->post_type === 'book' ) {
		$content ='<!-- wp:columns -->
		<div class="wp-block-columns"><!-- wp:column -->
		<div class="wp-block-column"><!-- wp:image -->
		<figure class="wp-block-image"><img alt=""/></figure>
		<!-- /wp:image --></div>
		<!-- /wp:column -->

		<!-- wp:column -->
		<div class="wp-block-column"><!-- wp:paragraph -->
		<!-- /wp:paragraph --></div>
		<!-- /wp:column --></div>
		<!-- /wp:columns -->';
	return $content;
add_filter( 'default_content', 'prefix_filter_book_content', 10, 2 );

– You can use other conditionals, for example checking for a specific author or post title.

Here I have created a new “Book” item through the WordPress admin area, and the block editor has placed the selected blocks for me:

The block editor shows the book custom post type with the default columns block.