register_block_pattern( string $pattern_name, array $pattern_properties ): bool

Registers a new block pattern.


Block pattern name including namespace.
List of properties for the block pattern.
See WP_Block_Patterns_Registry::register() for accepted arguments.


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


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



User Contributed Notes

  1. Skip to note 6 content

    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:

            '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 7 content

    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' );
  3. Skip to note 10 content

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

    function wpdocs_register_block_patterns() {
                    '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.