register_block_pattern( string $pattern_name, array $pattern_properties )

Registers a new pattern.

Parameters Parameters


(string) (Required) Pattern name including namespace.


(array) (Required) Array containing the properties of the pattern.

Top ↑

Return Return

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

Top ↑

Source 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 );

Top ↑

Changelog Changelog

Version Description
5.5.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    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:

            '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
    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' );

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