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

User Contributed Notes

1. Skip to note 6 content

   Christina Blust 4 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 10You must log in to vote on the helpfulness of this note

   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 -->",
       )
   );

   • As an addition to the category, I would like to give an example for those who did not know what syntax to use. Since a block pattern can be assigned to multiple categories you can use an array to place it in the right category. example:

           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 -->nn<!-- 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 -->", 		'categories'  => ['custom_category', 'columns'],        ) );  

     how to define/register a category can be found here: https://developer.wordpress.org/reference/functions/register_block_pattern_category/

     MangoWambo 4 years ago
2. Skip to note 7 content

   mikehealy 3 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 6You must log in to vote on the helpfulness of this note

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

   • Good call! Registering the block pattern straight from functions.php results in the editor crashing with an obscure JS error after opening the patterns pannel, without any PHP errors or warnings being triggered. Calling register_block_pattern inside the init hook solves this perfectly! Thanks!

     Jules Colle 3 years ago
3. Skip to note 8 content

   Márcio Duarte 2 years ago

   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

   Just a heads up for block theme developers: since WordPress 6.0 you can also register patterns in a block theme simply by placing PHP files with patterns in your theme’s /patterns subfolder.
4. Skip to note 9 content

   tomepajk 3 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

   If the core block patterns are removed via:

   remove_theme_support( 'core-block-patterns' );

   Make sure that there is at least one block pattern category registered. The block editor crashes if none are present.
5. Skip to note 10 content

   thejaydip 2 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

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