The WordPress block pattern inserter groups patterns into categories, things like “Featured”, “Text”, “Gallery”, and “Call to Action”. When you register your own custom patterns for a site or a plugin, they default to existing categories or no category at all. Registering your own category gives your patterns a dedicated, clearly labelled home in the inserter that’s separate from core and third-party patterns.
This is especially useful for plugin developers, agencies, and freelancers who deliver sites with a curated set of patterns. Grouping them under a branded category makes them easy for clients to find and signals that these are the approved, on-brand options.
The Code
Add this to your functions.php, a site-specific plugin, or your commercial plugin’s main file. Both functions run on the init hook, which is the correct point in the WordPress lifecycle for registering block patterns and categories.
Registering the Category
register_block_pattern_category() takes two arguments: a slug and an array of properties. The only required property is label, the human-readable name shown in the inserter. The slug should be lowercase, hyphenated if needed, and unique to avoid collisions with other plugins. Using your brand name or project namespace as the slug is the standard convention.
Registering a Pattern in the Category
The example pattern in the snippet demonstrates the minimum required fields: a namespaced slug (namespace/pattern-name), a title, a categories array referencing your new category slug, and the block markup content.
The content field contains serialised block markup, the same format WordPress stores in the database. The easiest way to generate this for your own patterns is to build the layout in the block editor, switch to Code Editor view, copy the markup, and paste it as the content string. Make sure to properly escape any quotes if you’re defining it as a PHP string, the snippet uses single quotes for the outer string, so double quotes inside the content don’t need escaping.
Additional Pattern Properties
The register_block_pattern() function supports several additional properties worth knowing about. description adds a tooltip shown when hovering the pattern in the inserter. keywords is an array of search terms that make the pattern discoverable when editors type in the pattern search field. viewportWidth sets the preview width in pixels, which is useful for patterns designed for specific breakpoints.
Organising Multiple Patterns
For sites with many custom patterns, consider splitting the pattern registration into separate files, one file per pattern, stored in a /patterns/ directory and loaded via require_once in a loop. WordPress 6.0 and later also supports auto-loading pattern files placed directly in the /patterns/ directory of a block theme, though this approach works for both classic and block themes when done programmatically.
add_action( 'init', function() {
// Register the custom category
register_block_pattern_category(
'nahnu', // Slug, use your brand or project name
[ 'label' => __( 'Nahnu Plugins', 'nahnu-snippets' ) ]
);
// Register an example pattern in the new category
register_block_pattern(
'nahnu/cta-banner',
[
'title' => __( 'CTA Banner', 'nahnu-snippets' ),
'categories' => [ 'nahnu' ],
'content' => '<!-- wp:group {"style":{"color":{"background":"#1e1b4b"}},"layout":{"type":"constrained"}} -->
<div class="wp-block-group has-background" style="background-color:#1e1b4b">
<!-- wp:heading {"textAlign":"center","style":{"color":{"text":"#f1f5f9"}}} -->
<h2 class="wp-block-heading has-text-align-center" style="color:#f1f5f9">Ready to get started?</h2>
<!-- /wp:heading -->
<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
<div class="wp-block-buttons">
<!-- wp:button -->
<div class="wp-block-button"><a class="wp-block-button__link wp-element-button">Get Started</a></div>
<!-- /wp:button -->
</div>
<!-- /wp:buttons -->
</div>
<!-- /wp:group -->',
]
);
} );