Registering Patterns Specific to Custom Post Types
When building a Custom Post Type (CPT) like "Portfolio," you often need specific layouts that don't make sense for standard blog posts. For example, a "Project Technical Specs" table or a "Before/After" image comparison.
Instead of cluttering the global pattern inserter, you can register Block Patterns that only appear when editing a specific post type.
1. The Magic Header: Post Types
In WordPress 6.1+, the Block Pattern API added a simple header to the PHP file registration method that handles this logic for you.
You don't need complex PHP filters anymore. You just need to add Post Types: portfolio to the file header.
2. Step-by-Step Example
Let's create a "Project Summary" pattern that is only available for the portfolio CPT.
Step A: Create the File
Create a new PHP file in your theme's patterns/ directory.
File: patterns/project-summary.php
Step B: Add the Code
<?php
/**
* Title: Project Summary Table
* Slug: my-theme/project-summary
* Categories: portfolio
* Post Types: portfolio
* Description: A summary table for project details (Client, Year, Role).
*/
?>
<!-- wp:group {"style":{"spacing":{"padding":{"top":"var:preset|spacing|40","bottom":"var:preset|spacing|40"},"blockGap":"var:preset|spacing|20"}},"backgroundColor":"light-gray","layout":{"type":"constrained"}} -->
<div class="wp-block-group has-light-gray-background-color has-background" style="padding-top:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--40)">
<!-- wp:heading -->
<h2 class="wp-block-heading">Project Details</h2>
<!-- /wp:heading -->
<!-- wp:table -->
<figure class="wp-block-table"><table><tbody>
<tr><td><strong>Client</strong></td><td>ACME Corp</td></tr>
<tr><td><strong>Year</strong></td><td>2024</td></tr>
<tr><td><strong>Services</strong></td><td>Web Design, FSE Development</td></tr>
</tbody></table></figure>
<!-- /wp:table -->
</div>
<!-- /wp:group -->Breakdown of Headers
Post Types: portfolio: This is the key. This pattern will only appear in the inserter when the user is editing a post of typeportfolio. It will be hidden for Posts and Pages.Categories: portfolio: It helps to group your CPT patterns into a specific category in the inserter. (See below on how to register this category).
3. Registering a Custom Pattern Category
If you used Categories: portfolio above, you need to ensure that category exists. Add this to functions.php:
function my_register_pattern_categories() {
register_block_pattern_category(
'portfolio',
array( 'label' => __( 'Portfolio', 'my-textdomain' ) )
);
}
add_action( 'init', 'my_register_pattern_categories' );4. Why Use This vs. Templates?
- Templates (e.g.,
single-portfolio.html) define the structure of the page (Header, Title location, Footer). - Patterns are for the content inside the editor.
Use this method when you want to give the editor a "Starter Layout" for the content area, or specific components they can drop in multiple times (like a "Testimonial" block specific to Case Studies).