{"id":47,"date":"2024-10-03T11:52:45","date_gmt":"2024-10-03T15:52:45","guid":{"rendered":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/?page_id=47"},"modified":"2025-08-15T10:32:47","modified_gmt":"2025-08-15T14:32:47","slug":"block-patterns","status":"publish","type":"page","link":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/best-practices\/block-patterns\/","title":{"rendered":"Managing Block Patterns"},"content":{"rendered":"\n<p class=\"has-medium-font-size\">A block pattern is a group of blocks combined to create reusable layout elements and page sections. Patterns allow users to add pre-designed, customizable elements to their content with a visual preview of the pattern. They help speed up template and page creation, and can be as small as a single block or as large as a full-page layout. <a href=\"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/handbook\/block-patterns\/\">Learn more in the Handbook<\/a>.<\/p>\n\n\n\n<h3>Core Patterns<\/h3>\n\n\n\n<p>Core patterns are included from two locations:<\/p>\n\n\n\n<ul><li>Some patterns are stored in the WordPress codebase and included with each version of WP. @todo &#8211; what are these?<\/li><li>Other core patterns are fetched remotely from the <a href=\"https:\/\/wordpress.org\/patterns\/\">WordPress Pattern Directory<\/a>. These patterns have proven to have issues working correctly in older versions of WP. It seems that the patterns in the Directory are not versioned to specific versions of WP.<\/li><\/ul>\n\n\n\n<hr class=\"wp-block-separator\"\/>\n\n\n\n<h2>Creating Custom Block Patterns<\/h2>\n\n\n\n<p>Patterns are available through a\u00a0<a href=\"https:\/\/developer.wordpress.org\/reference\/classes\/wp_block_patterns_registry\/\">block pattern registry class<\/a>\u00a0(WP 5.5+) and\u00a0<a href=\"https:\/\/developer.wordpress.org\/reference\/functions\/_register_theme_block_patterns\/\">private functions<\/a>\u00a0(WP 6+). Plugins and themes register the pattern, and the markup of the blocks is provided through a PHP function or in a file in the theme\u2019s patterns folder. Using the\u00a0<code>_register_theme_block_patterns<\/code>\u00a0function as a template, we&#8217;ll set up an init action doing the same thing (with a bail-out whenever we get to WP 6).<\/p>\n\n\n\n<h3>How to create a pattern and add it to a theme or plugin<\/h3>\n\n\n\n<p>In themes, there is <a href=\"https:\/\/github.com\/bu-ist\/responsive-child-starter-3x-block-editor\/tree\/develop\/patterns\">pattern folder<\/a> where designers\/devs can add new <code>pattern_name.php<\/code> file that will be automatically ingested using the _register_theme_block_patterns function.<\/p>\n\n\n\n<p>Patterns are available through a&nbsp;<a href=\"https:\/\/developer.wordpress.org\/reference\/classes\/wp_block_patterns_registry\/\">block pattern registry class<\/a>&nbsp;and&nbsp;<a href=\"https:\/\/developer.wordpress.org\/reference\/functions\/_register_theme_block_patterns\/\">private functions<\/a>.<\/p>\n\n\n\n<p>Plugins and themes register the pattern, and the markup of the blocks is provided through a PHP function or in a file in the theme\u2019s patterns folder.<\/p>\n\n\n\n<h3>Example Block Pattern<\/h3>\n\n\n\n<pre class=\"wp-block-code\"><code>&lt;?php\n\/**\n * Title: BU Test Pattern\n * Slug: responsive-child-starter-3x-block-editor\/bu-test-pattern\n * Categories: BU\n * Inserter: yes\n *\/\n\n?>\n\n&lt;!-- wp:media-text {\"align\":\"full\",\"mediaType\":\"image\",\"verticalAlignment\":\"center\"} -->\n&lt;div class=\"wp-block-media-text alignfull is-stacked-on-mobile is-vertically-aligned-center\">&lt;figure class=\"wp-block-media-text__media\">&lt;img src=\"https:\/\/s.w.org\/images\/core\/5.8\/architecture-04.jpg\" alt=\"Close-up, abstract view of architecture.\" \/>&lt;\/figure>&lt;div class=\"wp-block-media-text__content\">&lt;!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"style\":{\"color\":{\"text\":\"#000000\"}}} -->\n&lt;h3 class=\"wp-block-heading has-text-align-center has-text-color\" style=\"color:#000000\">&lt;strong>Open Spaces&lt;\/strong>&lt;\/h3>\n&lt;!-- \/wp:heading -->\n\n&lt;!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"extra-small\"} -->\n&lt;p class=\"has-text-align-center has-extra-small-font-size\">&lt;a href=\"#\">See case study \u2197&lt;\/a>&lt;\/p>\n&lt;!-- \/wp:paragraph -->&lt;\/div>&lt;\/div>\n&lt;!-- \/wp:media-text --><\/code><\/pre>\n\n\n\n<h3>How to use&nbsp;<code>register_block_pattern()<\/code><\/h3>\n\n\n\n<p>Being able to register patterns conditionally is one use case for using the PHP function instead of the patterns folder. To add patterns in a theme or plugin, you can register standard (unsynced) block patterns using the PHP function\u00a0<a href=\"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/block-api\/block-patterns\/#register_block_pattern\">register_block_pattern()<\/a>\u00a0together with an\u00a0<a href=\"https:\/\/developer.wordpress.org\/reference\/hooks\/init\/\">init<\/a>\u00a0hook:<\/p>\n\n\n\n<p>In functions.php:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>function prefix_block_pattern() {\n  register_block_pattern( ... );\n}\n \nadd_action( 'init', 'prefix_block_pattern' );<\/code><\/pre>\n\n\n\n<p>In my example, I am going to use and style a contact form provided by&nbsp;<a href=\"https:\/\/wordpress.org\/plugins\/ninja-forms\/\">Ninja Forms<\/a>, so first, I am going to check if this plugin is active:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>if ( function_exists( 'register_block_pattern' ) &amp;&amp;\n        function_exists( 'ninja_forms' ) ) {\n                register_block_pattern( ... );\n        }\n}<\/code><\/pre>\n\n\n\n<p>The first property inside the register_block_pattern function is the unique identifier. The identifier includes a prefix or namespace (the theme slug), followed by a forward slash and a slug for the pattern. Examples:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>register_block_pattern(\n\t'prefix\/pattern-slug',\n         ...<\/code><\/pre>\n\n\n\n<p>As in:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>register_block_pattern(\n\t'twentytwentytwo\/contact-form',\n         ...<\/code><\/pre>\n\n\n\n<p>The identifier is followed by an array of properties, as I described earlier:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>register_block_pattern(\n\t'prefix\/contact-form',\n\tarray(\n\t\t'title'      => The visible name in the editor,\n\t\t'categories' => An array of categories,\n\t\t'content'    => The block markup,\n\t)\n);<\/code><\/pre>\n\n\n\n<p>Remember to wrap the title, keywords and description inside translation functions!<\/p>\n\n\n\n<hr class=\"wp-block-separator\"\/>\n\n\n\n<h2>Disabling Block Patterns<\/h2>\n\n\n\n<p>Block patterns and most of the block pattern categories can be unregistered. The reasoning behind this is we don&#8217;t want to be on the hook for supporting all the core patterns (especially ones utilizing group and column blocks) in case they break or the markup changes in upgrades. This will allow us to create our own using our BU-specific, supported blocks to offer clients similar flexibility.<\/p>\n\n\n\n<p>This will remove and disable core block patterns including those remotely fetched.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>add_action( 'after_setup_theme', 'themeslug_remove_core_patterns' );\n\nfunction themeslug_remove_core_patterns() {\n\tremove_theme_support( 'core-block-patterns' );\n}<\/code><\/pre>\n\n\n\n<p>You need to add this code using an init hook or&nbsp;<a href=\"https:\/\/developer.wordpress.org\/reference\/hooks\/after_setup_theme\/\">after_setup_theme<\/a>, and you will most likely place this inside a function with the rest of your theme support.<\/p>\n\n\n\n<p>To remove a single block pattern, use the PHP function&nbsp;<a href=\"https:\/\/developer.wordpress.org\/block-editor\/developers\/block-api\/block-patterns\/#unregister_block_pattern\">unregister_block_pattern<\/a>&nbsp;together with the pattern prefix and slug:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>unregister_block_pattern( 'prefix\/my-awesome-pattern' );<\/code><\/pre>\n\n\n\n<p>If you want to remove a single pattern that is included in WordPress, core, use core as the prefix. This also works for block patterns created by plugins; all you need is the pattern\u2019s name and prefix.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>unregister_block_pattern( 'core\/two-buttons' );<\/code><\/pre>\n\n\n\n<p><a href=\"https:\/\/developer.wordpress.org\/themes\/features\/block-patterns\/#disabling-remote-patterns\">There is a filter to remove just remotely fetched block patterns<\/a>\u00a0and keep the core patterns included in the WP core codebase:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>add_filter( 'should_load_remote_block_patterns', '__return_false' );<\/code><\/pre>\n\n\n\n<hr class=\"wp-block-separator\"\/>\n\n\n\n<h2>Adding custom styles to a pattern in the editor &amp; frontend<\/h2>\n\n\n\n<h3>Add CSS classes to patterns<\/h3>\n\n\n\n<p>Custom CSS styled block patterns should only be used for patterns registered in a custom theme and<span>\u00a0<\/span><em style=\"box-sizing: border-box;\">not<\/em><span>\u00a0<\/span>plugins.<\/p>\n\n\n\n<p>We can add CSS classes to block patterns to allow us to style the pattern, without giving<span>\u00a0<\/span><em style=\"box-sizing: border-box;\">full<\/em><span>\u00a0<\/span>control of the styles to clients.<\/p>\n\n\n\n<p>Per<span>&nbsp;<\/span><a href=\"https:\/\/fullsiteediting.com\/lessons\/introduction-to-block-patterns\/#h-how-to-add-a-css-class-to-a-block-pattern\" rel=\"nofollow\" style=\"box-sizing: border-box; background-color: transparent; color: var(--fgcolor-accent, var(--color-accent-fg)); text-decoration: underline; text-underline-offset: 0.2rem;\">FullSiteEditing<\/a>, you can add a CSS class to the wrapper element and use that selector to style your pattern.<\/p>\n\n\n\n<p>In the example, I am using the cover block as the wrapper.<\/p>\n\n\n\n<p>First, add the className attribute inside the block comment, where the value is the CSS class.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>&lt;!-- wp:cover {\"className\":\"prefix-contact-form\", ...<\/code><\/pre>\n\n\n\n<p>You need to duplicate this for the wrapping div. Place the class name inside the class attribute:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>&lt;div class=\"wp-block-cover prefix-contact-form <\/code><\/pre>\n\n\n\n<h2>Further Reading<\/h2>\n\n\n\n<ul><li><a href=\"https:\/\/learn.wordpress.org\/tutorial\/intro-to-block-patterns\/\">https:\/\/learn.wordpress.org\/tutorial\/intro-to-block-patterns\/<\/a><\/li><li><a href=\"https:\/\/wordpress.org\/patterns\/\">https:\/\/wordpress.org\/patterns\/<\/a><\/li><li><a href=\"https:\/\/gutenberg.10up.com\/reference\/Blocks\/block-patterns\/\">https:\/\/gutenberg.10up.com\/reference\/Blocks\/block-patterns\/<\/a><\/li><li><a href=\"https:\/\/fullsiteediting.com\/lessons\/introduction-to-block-patterns\/\">https:\/\/fullsiteediting.com\/lessons\/introduction-to-block-patterns\/<\/a><\/li><li><a href=\"https:\/\/fullsiteediting.com\/lessons\/introduction-to-block-patterns\/#h-how-to-display-the-pattern-selection-when-creating-a-new-page\">https:\/\/fullsiteediting.com\/lessons\/introduction-to-block-patterns\/#h-how-to-display-the-pattern-selection-when-creating-a-new-page<\/a><\/li><li><a href=\"https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/block-api\/block-patterns\/#register_block_pattern\">https:\/\/developer.wordpress.org\/block-editor\/reference-guides\/block-api\/block-patterns\/#register_block_pattern<\/a><\/li><\/ul>\n","protected":false},"excerpt":{"rendered":"<p>A block pattern is a group of blocks combined to create reusable layout elements and page sections. Patterns allow users to add pre-designed, customizable elements to their content with a visual preview of the pattern. They help speed up template and page creation, and can be as small as a single block or as large [&hellip;]<\/p>\n","protected":false},"author":3670,"featured_media":0,"parent":581,"menu_order":7,"comment_status":"closed","ping_status":"closed","template":"","meta":[],"status-is-a-reserved-term":[5],"assignee":[4],"_links":{"self":[{"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/pages\/47"}],"collection":[{"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/users\/3670"}],"replies":[{"embeddable":true,"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/comments?post=47"}],"version-history":[{"count":5,"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/pages\/47\/revisions"}],"predecessor-version":[{"id":410,"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/pages\/47\/revisions\/410"}],"up":[{"embeddable":true,"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/pages\/581"}],"wp:attachment":[{"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/media?parent=47"}],"wp:term":[{"taxonomy":"status-is-a-reserved-term","embeddable":true,"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/status-is-a-reserved-term?post=47"},{"taxonomy":"assignee","embeddable":true,"href":"https:\/\/id-developer-upgrade-58.cms-devl.bu.edu\/gutenberg\/wp-json\/wp\/v2\/assignee?post=47"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}