register_block_pattern( string $pattern_name, array $pattern_properties )

Registers a new block pattern.

Contents

Parameters

$pattern_name

(string) (Required) Block pattern name including namespace.

$pattern_properties

(array) (Required) List of properties for the block pattern. See WP_Block_Patterns_Registry::register() for accepted arguments.

Top ↑

Return

(bool) True if the pattern was registered with success and false otherwise.

Top ↑

Source

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

function register_block_pattern( $pattern_name, $pattern_properties ) {
	return WP_Block_Patterns_Registry::get_instance()->register( $pattern_name, $pattern_properties );
}

Expand full source code Collapse full source code View on Trac View on GitHub

Top ↑

Top ↑

Used By

Used By
Used By Description
wp-includes/block-patterns.php: _register_remote_theme_patterns()

Registers patterns from Pattern Directory provided by a theme’s theme.json file.
wp-includes/block-patterns.php: _register_theme_block_patterns()

Register any patterns that the active theme may provide under its ./patterns/ directory. Each pattern is defined as a PHP file and defines its metadata using plugin-style headers. The minimum required definition is:
wp-includes/block-patterns.php: _load_remote_featured_patterns()

Register Featured (category) patterns from wordpress.org/patterns.
wp-includes/block-patterns.php: _load_remote_block_patterns()

Register Core’s official patterns from wordpress.org/patterns.
wp-includes/block-patterns.php: _register_core_block_patterns_and_categories()

Registers the core block patterns and categories.

Top ↑

Changelog

Changelog
Version Description
5.5.0 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 7You must log in to vote on the helpfulness of this note
    Contributed by Christina Blust —

    Per the Block Patterns documentation in the Block Editor Handbook, the $pattern_properties array includes:

    • title (required): A human-readable title for the pattern.
    • content (required): Raw HTML content for the pattern.
    • description: A visually hidden text used to describe the pattern in the inserter. A description is optional but it is strongly encouraged when the title does not fully describe what the pattern does.
    • categories: A list of pattern categories used to group block patterns. Block patterns can be shown on multiple categories.
    • keywords: Aliases or keywords that help users discover it while searching.
    • viewportWidth: Specify the width of the pattern in the inserter.

    and the example function given is:

    register_block_pattern(
    'wpdocs-my-plugin/my-awesome-pattern',
    array(
        'title'       => __( 'Two buttons', 'wpdocs-my-plugin' ),
        'description' => _x( 'Two horizontal buttons, the left button is filled in, and the right button is outlined.', 'Block pattern description', 'wpdocs-my-plugin' ),
        'content'     => "<!-- wp:buttons {\"align\":\"center\"} -->\n<div class=\"wp-block-buttons aligncenter\"><!-- wp:button {\"backgroundColor\":\"very-dark-gray\",\"borderRadius\":0} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-background has-very-dark-gray-background-color no-border-radius\">" . esc_html__( 'Button One', 'wpdocs-my-plugin' ) . "</a></div>\n<!-- /wp:button -->\n\n<!-- wp:button {\"textColor\":\"very-dark-gray\",\"borderRadius\":0,\"className\":\"is-style-outline\"} -->\n<div class=\"wp-block-button is-style-outline\"><a class=\"wp-block-button__link has-text-color has-very-dark-gray-color no-border-radius\">" . esc_html__( 'Button Two', 'wpdocs-my-plugin' ) . "</a></div>\n<!-- /wp:button --></div>\n<!-- /wp:buttons -->",
    )
);
  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note
    Contributed by mikehealy —

    The docs & handbook don’t seem to mention it, but I gather register_block_pattern() should be called from a handler attached to the init hook.

    function wpdocs_register_my_patterns() {
  register_block_pattern( ... );
}

add_action( 'init', 'wpdocs_register_my_patterns' );
  4. Skip to note 4 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by thejaydip —

    A basic example of how to register a new pattern block.

    function wpdocs_register_block_patterns() {
        register_block_pattern(
            'wpdocs/my-example',
            array(
                'title'         => __( 'My First Block Pattern', 'textdomain' ),
                'description'   => _x( 'This is my first block pattern', 'Block pattern description', 'textdomain' ),
                'content'       => '<!-- wp:paragraph --><p>A single paragraph block style</p><!-- /wp:paragraph -->',
                'categories'    => array( 'text' ),
                'keywords'      => array( 'cta', 'demo', 'example' ),
                'viewportWidth' => 800,
            )
        );
}
add_action( 'init', 'wpdocs_register_block_patterns' );

You must log in before being able to contribute a note or feedback.