How to register a block template part from plugins?

[daviedR]

Since WordPress 6.7, there's a new register_block_template API which can be used by plugins to register a custom block template.

But how can we add a block template part from plugins?

[talldan]

Sorry for the delay in replying. Adding a register_block_template_part function was considered, but there's some discussion about merging the concepts of template parts and patterns, so in the future, I expect this will be possible via register_block_pattern.

[daviedR]

Thanks for your reply!
Is there any ETA on when the merging will be implemented into the core release?

[talldan]

I don't have any timeline, it's also difficult to provide a stopgap measure because of the way backwards compatibility in WordPress works.

I know there are still ways to add template parts via filters, I think WooCommerce does this, so that might be something to look into.

[daviedR]

Yes, WooCommerce does it via the get_block_templates filter. It looks a bit too complex, but I will look into it again.

[mrleemon]

Hi @talldan, checking back in on this now that some time has passed. Has there been any further progress on merging template parts and patterns, or is there a new recommended way to register template parts from a plugin in the latest versions of WordPress? Thanks!

[rajpratham1]

To register a block template part from a plugin, you can use the register_block_template_part() function (WordPress 6.1+).

You can do it like this:

add_action( 'init', function() {
    register_block_template_part(
        'my-plugin/header',
        array(
            'title'       => 'Plugin Header',
            'description' => 'Header template part added by my plugin.',
            'area'        => 'header',
            'content'     => '<!-- wp:paragraph --><p>This is my custom header</p><!-- /wp:paragraph -->',
        )
    );
});

Make sure:

• It runs inside the init hook
• The slug is unique (like my-plugin/header)
• The area matches a valid theme area (header, footer, etc.)

[mrleemon]

There's no register_block_template_part() function

[rajpratham1]

You're correct — there is no register_block_template_part() function in WordPress core.

Block template parts cannot be registered via a PHP API like blocks (register_block_type()).

Instead, there are two supported approaches:

---

1️⃣ Automatically via a Block Theme

If you're using a block theme, template parts are automatically discovered when placed inside:

/your-theme/parts/*.html

Example:

/parts/header.html

No PHP registration is required.

---

2️⃣ Programmatically via the wp_template_part Post Type (From a Plugin)

If you need to add a template part from a plugin, you must create a wp_template_part post programmatically:

add_action( 'init', function() {

    if ( ! function_exists( 'wp_is_block_theme' ) || ! wp_is_block_theme() ) {
        return;
    }

    $slug = 'my-plugin-header';

    // Avoid duplicate creation
    if ( get_page_by_path( $slug, OBJECT, 'wp_template_part' ) ) {
        return;
    }

    wp_insert_post( array(
        'post_type'    => 'wp_template_part',
        'post_title'   => 'Plugin Header',
        'post_name'    => $slug,
        'post_status'  => 'publish',
        'post_content' => '<!-- wp:paragraph --><p>This is my custom header</p><!-- /wp:paragraph -->',
        'tax_input'    => array(
            'wp_template_part_area' => array( 'header' ),
        ),
    ) );

});

---

Summary

Template parts are:

• Automatically registered from /parts in block themes
• Or stored as wp_template_part posts
• Managed by the Site Editor

There is no register_block_template_part() function in WordPress core.

[s-a-s-k-i-a]

Just to clarify the answer above before someone copies it into production: there is no register_block_template_part() function in WordPress core as of 6.7 / Gutenberg trunk. Calling it will throw Call to undefined function. The symmetry with register_block_template() is intuitive but the template-part equivalent was discussed and not landed — partly because of the convergence between template parts and patterns @talldan referenced.

Working approaches from a plugin today:

1. Register a block pattern scoped to a template-part area — closest first-party route. The pattern shows up in the Site Editor under "Add → Template part" for the matching area:

add_action( 'init', function () {
    register_block_pattern( 'my-plugin/header', [
        'title'         => __( 'My Plugin Header', 'my-plugin' ),
        'content'       => '<!-- wp:group --><div class="wp-block-group">…</div><!-- /wp:group -->',
        'blockTypes'    => [ 'core/template-part/header' ],
        'templateTypes' => [ 'header' ],
    ] );
} );

The user still instantiates the part themselves, but your plugin owns the content. templateTypes was added to the pattern registry in 6.2.

2. Extend default_wp_template_part_areas if you need a custom area (e.g. aside):

add_filter( 'default_wp_template_part_areas', function ( $areas ) {
    $areas[] = [
        'area'        => 'aside',
        'label'       => __( 'Aside', 'my-plugin' ),
        'description' => __( 'Sidebar template parts.', 'my-plugin' ),
        'icon'        => 'aside',
        'area_tag'    => 'aside',
    ];
    return $areas;
} );

(Filter is in wp-includes/block-template-utils.php::get_allowed_block_template_part_areas().)

3. Ship a companion block theme if you really need plugin-owned parts/*.html files treated as first-class template parts. Only themes can do that today; it's the workaround most plugin authors fall back on when patterns aren't enough.

Worth a +1 on the existing tracking issue under the [Block Templates] label if a plugin-side API matters to you.

[rajpratham1]

Thanks for the detailed clarification — this explains the current state much better. I originally assumed there was a template-part equivalent to register_block_template() because the API naming feels like it should exist, but clearly that hasn’t landed in core yet.

The block pattern approach scoped to template-part areas seems like the most future-friendly solution for plugins right now, especially since it integrates nicely with the Site Editor without relying on custom wp_template_part post creation.

Also appreciate the note about extending default_wp_template_part_areas — that’s a really useful detail for custom plugin layouts. Hopefully WordPress eventually introduces an official plugin-side API for template parts, because this is definitely a common need in block-based development.