WP_Block_Patterns_Registry

Last updated: March 4, 2026

The WP_Block_Patterns_Registry class manages all registered block patterns in WordPress. It follows the singleton pattern, providing a centralized registry for pattern storage and retrieval.

File: wp-includes/class-wp-block-patterns-registry.php
Since: 5.5.0

Class Synopsis

php
final class WP_Block_Patterns_Registry {
    // Properties
    private array $registered_patterns = [];
    private array $registered_patterns_outside_init = [];
    private static ?WP_Block_Patterns_Registry $instance = null;

    // Methods
    public function register( string $pattern_name, array $pattern_properties ): bool;
    public function unregister( string $pattern_name ): bool;
    public function get_registered( string $pattern_name ): ?array;
    public function get_all_registered( bool $outside_init_only = false ): array;
    public function is_registered( string $pattern_name ): bool;
    public static function get_instance(): WP_Block_Patterns_Registry;
    
    // Private methods
    private function get_content( string $pattern_name, bool $outside_init_only = false ): string;
}

Properties

$registered_patterns

php
private array $registered_patterns = [];

Stores all registered block patterns keyed by pattern name.

Since: 5.5.0

$registered_patterns_outside_init

php
private array $registered_patterns_outside_init = [];

Stores patterns registered outside the init action. Used to detect deprecated registration timing (e.g., during admin_init or current_screen).

Since: 6.0.0

$instance

php
private static ?WP_Block_Patterns_Registry $instance = null;

Container for the singleton instance.

Since: 5.5.0

Methods

get_instance()

Retrieves the singleton instance of the registry.

php
public static function get_instance(): WP_Block_Patterns_Registry

Returns: The main WP_Block_Patterns_Registry instance.

Example:

php
$registry = WP_Block_Patterns_Registry::get_instance();

Since: 5.5.0

register()

Registers a block pattern.

php
public function register( string $pattern_name, array $pattern_properties ): bool

Parameters:

ParameterTypeDescription
$pattern_namestringBlock pattern name including namespace
$pattern_propertiesarrayPattern properties (see below)

Pattern Properties:

PropertyTypeRequiredSinceDescription
titlestringYes5.5.0Human-readable pattern title
contentstringConditional5.5.0Block HTML markup
filePathstringConditional6.5.0Path to PHP file with content
descriptionstringNo5.5.0Hidden description for discovery
viewportWidthintNo5.5.0Preview width in inserter
inserterboolNo5.5.0Show in inserter (default: true)
categoriesstring[]No5.5.0Category slugs
keywordsstring[]No5.5.0Search keywords
blockTypesstring[]No5.8.0Associated block types
postTypesstring[]No6.1.0Post type restrictions
templateTypesstring[]No6.2.0Template type associations

Returns: true on success, false on failure.

Validation:

  • Pattern name must be a string
  • Title must be a string
  • Either content or filePath must be provided

Example:

php
$registry = WP_Block_Patterns_Registry::get_instance();

$registry->register(
    'my-plugin/hero',
    array(
        'title'      => 'Hero Section',
        'categories' => array( 'banner' ),
        'content'    => '<!-- wp:cover -->...',
    )
);

Since: 5.5.0

unregister()

Unregisters a block pattern.

php
public function unregister( string $pattern_name ): bool

Parameters:

ParameterTypeDescription
$pattern_namestringPattern name to unregister

Returns: true on success, false if pattern not found.

Behavior:

  • Removes from both $registered_patterns and $registered_patterns_outside_init
  • Triggers _doing_it_wrong() if pattern doesn’t exist

Example:

php
$registry = WP_Block_Patterns_Registry::get_instance();
$registry->unregister( 'core/query-standard-posts' );

Since: 5.5.0

get_registered()

Retrieves properties of a registered pattern.

php
public function get_registered( string $pattern_name ): ?array

Parameters:

ParameterTypeDescription
$pattern_namestringPattern name to retrieve

Returns: Pattern properties array, or null if not registered.

Behavior:

  • Resolves filePath to actual content if needed
  • Processes content through Block Hooks system
  • Returns complete pattern with name property added

Example:

php
$registry = WP_Block_Patterns_Registry::get_instance();
$pattern = $registry->get_registered( 'core/query-grid-posts' );

if ( $pattern ) {
    echo $pattern['title'];   // "Grid"
    echo $pattern['content']; // Block markup
}

Since: 5.5.0

get_all_registered()

Retrieves all registered patterns.

php
public function get_all_registered( bool $outside_init_only = false ): array

Parameters:

ParameterTypeDescription
$outside_init_onlyboolReturn only patterns registered outside init

Returns: Indexed array of pattern property arrays.

Behavior:

  • Resolves all filePath patterns to content
  • Processes all content through Block Hooks
  • Returns array values (not keyed by name)

Example:

php
$registry = WP_Block_Patterns_Registry::get_instance();

// Get all patterns
$all_patterns = $registry->get_all_registered();
foreach ( $all_patterns as $pattern ) {
    echo $pattern['name'] . ': ' . $pattern['title'] . "n";
}

// Get only patterns registered late (debugging)
$late_patterns = $registry->get_all_registered( true );

Since: 5.5.0

is_registered()

Checks if a pattern is registered.

php
public function is_registered( ?string $pattern_name ): bool

Parameters:

ParameterTypeDescription
$pattern_namestring|nullPattern name to check

Returns: true if registered, false otherwise.

Example:

php
$registry = WP_Block_Patterns_Registry::get_instance();

if ( $registry->is_registered( 'core/query-standard-posts' ) ) {
    // Pattern exists
}

if ( ! $registry->is_registered( 'my-plugin/hero' ) ) {
    // Register it
    $registry->register( 'my-plugin/hero', $props );
}

Since: 5.5.0

get_content() (private)

Retrieves and caches pattern content.

php
private function get_content( string $pattern_name, bool $outside_init_only = false ): string

Behavior:

  • If pattern has filePath but no content, includes the file and captures output
  • Caches the content in the pattern array
  • Removes filePath after content is resolved

Since: 6.5.0

__wakeup()

Handles unserialization security.

php
public function __wakeup(): void

Behavior:

  • Validates $registered_patterns is an array
  • Validates each pattern is an array
  • Throws UnexpectedValueException on invalid data
  • Clears $registered_patterns_outside_init

Block Hooks Integration

When retrieving patterns via get_registered() or get_all_registered(), content is processed through the Block Hooks system:

php
$pattern['content'] = apply_block_hooks_to_content(
    $content,
    $pattern,
    'insert_hooked_blocks_and_set_ignored_hooked_blocks_metadata'
);

This allows hooked blocks to be automatically inserted into pattern content.

Usage Patterns

Check Before Register

php
$registry = WP_Block_Patterns_Registry::get_instance();

if ( ! $registry->is_registered( 'my-plugin/hero' ) ) {
    $registry->register( 'my-plugin/hero', array(
        'title'   => 'Hero',
        'content' => '<!-- wp:cover -->...',
    ) );
}

Override Existing Pattern

php
add_action( 'init', function() {
    $registry = WP_Block_Patterns_Registry::get_instance();
    
    // Unregister and re-register with modifications
    if ( $registry->is_registered( 'theme/hero' ) ) {
        $original = $registry->get_registered( 'theme/hero' );
        $registry->unregister( 'theme/hero' );
        
        $registry->register( 'theme/hero', array_merge(
            $original,
            array( 'categories' => array( 'featured' ) )
        ) );
    }
}, 20 );

List Pattern Names

php
$registry = WP_Block_Patterns_Registry::get_instance();
$all_patterns = $registry->get_all_registered();

$pattern_names = array_column( $all_patterns, 'name' );
// ['core/query-standard-posts', 'core/query-grid-posts', ...]

Filter Patterns by Category

php
$registry = WP_Block_Patterns_Registry::get_instance();
$all_patterns = $registry->get_all_registered();

$banner_patterns = array_filter( $all_patterns, function( $pattern ) {
    return isset( $pattern['categories'] ) 
        && in_array( 'banner', $pattern['categories'], true );
});

Wrapper Functions

For convenience, use these wrapper functions instead of accessing the registry directly:

php
// Register pattern
register_block_pattern( $name, $properties );

// Unregister pattern
unregister_block_pattern( $name );

See Pattern Functions for details.

Version History

VersionChanges
5.5.0Class introduced
5.8.0blockTypes property support
6.0.0$registered_patterns_outside_init tracking
6.1.0postTypes property support
6.2.0templateTypes property support
6.5.0filePath property and get_content() method

More in Block Patterns

Block Pattern Functions

WordPress provides wrapper functions for registering and managing block patterns and pattern categories. Pattern Functions…

Block Patterns Hooks

Filters and actions for customizing block pattern behavior. Filters should_load_remote_block_patterns Controls whether patterns are loaded…

All WordPress Core Docs View all Block Patterns
View on GitHub