How to Filter Templates in the Block Editor's Swap Template Modal

Many WordPress developers working with block themes have encountered a specific challenge: the "Swap template" modal in the site editor shows a list of all available templates, including archive templates that are not relevant when editing a single page or post. This can be confusing for content editors and clutter the interface. This guide explains the problem and provides a potential solution based on community findings.

Understanding the Problem

When a user clicks the "Swap template" button while editing a page or post in the block editor, a modal window appears. This modal pulls its list of available templates from a WordPress REST API endpoint. By default, this list is comprehensive and includes templates of all types, such as those designed for archives, categories, tags, and other taxonomy-based content. For a user who is simply trying to change the template for a single page, seeing these irrelevant archive templates is unnecessary and can lead to mistakes.

Why This Happens

The core issue is that the standard WordPress filters used for the classic editor, such as theme_page_templates, do not affect the list of templates shown in the block editor's modal. This modal is powered by a different mechanism that queries the REST API directly. Furthermore, the context of the request (e.g., whether it's for a page, post, or custom post type) is not readily available in the same way, making it difficult to filter the list conditionally.

Potential Solutions and Workarounds

Based on community discussion, a direct, officially documented filter for this specific REST API response is not readily available. However, one potential approach involves intercepting and modifying the REST API request itself.

Method: Filtering the REST API Response

The most promising solution is to use the rest_prepare_wp_template filter hook. This filter allows you to modify the data of a single template object right before it is returned by the REST API. By using this filter, you could theoretically examine each template and conditionally remove it from the collection based on its properties.

Here is a conceptual code example to illustrate this approach:

function filter_swap_modal_templates( $response, $post, $request ) {
    // Check if this request is likely for the Swap Template modal
    // This might involve checking the request context or parameters
    $context = $request->get_param( 'context' );
    
    if ( $context === 'edit' ) {
        // Get the current template data
        $data = $response->get_data();
        
        // Example: Check if the template is an archive type
        if ( isset( $data['slug'] ) && strpos( $data['slug'], 'archive' ) !== false ) {
            // Returning null may remove it from the list
            return null;
        }
    }
    return $response;
}
add_filter( 'rest_prepare_wp_template', 'filter_swap_modal_templates', 10, 3 );

Important Note: This code is a starting point for development and has not been fully tested. The exact implementation will depend on the specific templates you need to filter and the available data in the $response object. The challenge is accurately identifying the context of the request to ensure you only filter the templates when they are being fetched for the Swap Template modal and not for other admin functions.

Conclusion and Further Steps

Filtering the templates in the Swap Template modal is an advanced topic that requires custom development. The solution likely lies in carefully using the rest_prepare_wp_template filter or another related REST API filter. Developers are encouraged to explore the structure of the API response using browser developer tools and to test their filtering logic thoroughly.

As this functionality is core to WordPress, it is also recommended to keep an eye on official WordPress development blogs and Trac tickets, as a more straightforward filter or method for this specific use case may be introduced in a future update.