register_block_pattern_category()
Registers a new category for block patterns to group them in the block editor.
Custom custom block patterns can be added to this category. This simplifies the organization and search for patterns in the editor.
It is recommended to call on the init hook.
Important: the category will only be displayed in the editor if at least one pattern has been added to it.
The category is specified in the parameter categories.
When registering a pattern via register_block_pattern():
add_action( 'init', 'my_plugin_register_patterns' );
function my_plugin_register_patterns() {
register_block_pattern(
'my-plugin/two-buttons',
[
'title' => __( 'Two Buttons', 'my-plugin' ),
'categories' => [ 'buttons' ],
'content' => '
<!-- wp:buttons {"align":"center"} -->
...
<!-- /wp:buttons -->
',
]
);
}
In themes, patterns can be created by adding a PHP file to the /patterns folder, with the pattern parameters specified in the comments of the PHP file:
<?php /** * Title: Example * Slug: theme/example * Categories: agnostic_page */
Core patterns are registered in the file wp-includes/block-patterns.php.
The list of core pattern categories is - _register_core_block_patterns_and_categories():
banner — Highlighted sections for showcasing key content. buttons — Patterns containing buttons and calls to action. columns — Multi-column patterns with more complex layouts. text — Patterns primarily containing text. query — Displaying the latest posts in lists, grids, and other layouts. featured — A collection of high-quality and hand-picked patterns. call-to-action — Sections aimed at prompting a specific action. team — Various designs for displaying team members. testimonials — Reviews and opinions about your brand or business. services — A brief description of your activities and how you can be helpful. contact — Displaying contact information. about — Introducing yourself or your company. portfolio — Portfolio — showcasing your latest works. gallery — Various layouts for displaying images. media — Layouts including video or audio. videos — Various layouts with video content. audio — Various layouts with audio content. posts — Displaying the latest posts in lists, grids, and other layouts. footer — Various footer designs with information and site navigation. header — Various header designs with site name and navigation.
Use unregister_block_pattern_category() when you need to remove (delete) a category.
No Hooks.
Returns
true|false.
true- if the category is successfully registered.false- otherwise.
Usage
register_block_pattern_category( $category_name, $category_properties );
- $category_name(string) (required)
- Unique identifier for the category (slug). It is recommended to use a prefix of the plugin or theme.
- $category_properties(array) (required)
Array of category properties. Available fields:
label(string) — Name of the category.description(string) — Description of the category (optional).
Examples
#1 Registration of the "Hero" category
Creates the "Hero" category for patterns related to headings.
add_action( 'init', 'my_plugin_register_pattern_categories' );
function my_plugin_register_pattern_categories() {
register_block_pattern_category(
'my-plugin-hero',
[
'label' => __( 'Hero', 'my-plugin' ),
'description' => __( 'Patterns related to headings.', 'my-plugin' ),
]
);
} #2 Checking for the existence of a category before registration
Avoids re-registering the category if it already exists.
add_action( 'init', 'my_plugin_register_pattern_categories' );
function my_plugin_register_pattern_categories() {
$registry = WP_Block_Pattern_Categories_Registry::get_instance();
if ( ! $registry->is_registered( 'my-plugin-hero' ) ) {
register_block_pattern_category(
'my-plugin-hero',
[
'label' => __( 'Hero', 'my-plugin' ),
]
);
}
} #3 List of all categories via JS
To get a list of all registered categories, insert the following into the JS inspector:
wp.data.select('core').getBlockPatternCategories()
Changelog
| Since 5.5.0 | Introduced. |
register_block_pattern_category() register block pattern category code WP 6.9
function register_block_pattern_category( $category_name, $category_properties ) {
return WP_Block_Pattern_Categories_Registry::get_instance()->register( $category_name, $category_properties );
}