{"id":5523,"date":"2026-02-12T20:44:41","date_gmt":"2026-02-13T01:44:41","guid":{"rendered":"https:\/\/chubes.net\/?documentation=block-patterns-api-overview"},"modified":"2026-03-13T03:27:52","modified_gmt":"2026-03-13T07:27:52","slug":"block-patterns-api-overview","status":"publish","type":"documentation","link":"https:\/\/chubes.net\/docs\/wordpress-core\/block-patterns\/block-patterns-api-overview\/","title":{"rendered":"Block Patterns API Overview"},"content":{"rendered":"<p>Block patterns are predefined block layouts that users can insert into content with a single click. Introduced in WordPress 5.5, patterns provide reusable design templates ranging from simple text layouts to complex multi-column designs.<\/p><h2 class=\"wp-block-heading\">Core Concepts<\/h2><h3 class=\"wp-block-heading\">What Are Block Patterns?<\/h3><p>Block patterns are collections of blocks that form a cohesive design unit. Unlike reusable blocks (synced patterns), block patterns are templates\u2014inserting a pattern creates a copy that can be freely modified without affecting the original.<\/p><p><strong>Pattern Properties:<\/strong><\/p><ul class=\"wp-block-list\"><li><code>name<\/code> &#8211; Unique identifier with namespace (e.g., <code>my-plugin\/hero-section<\/code>)<\/li><li><code>title<\/code> &#8211; Human-readable display name (required)<\/li><li><code>content<\/code> &#8211; Block HTML markup or <code>filePath<\/code> to a PHP file (required)<\/li><li><code>description<\/code> &#8211; Hidden text for search\/discovery<\/li><li><code>categories<\/code> &#8211; Array of category slugs for organization<\/li><li><code>keywords<\/code> &#8211; Search aliases<\/li><li><code>blockTypes<\/code> &#8211; Blocks that can use this pattern (transforms, placeholders)<\/li><li><code>postTypes<\/code> &#8211; Restrict pattern to specific post types<\/li><li><code>templateTypes<\/code> &#8211; Template types where pattern fits (e.g., <code>404<\/code>, <code>single<\/code>)<\/li><li><code>viewportWidth<\/code> &#8211; Preview width in inserter<\/li><li><code>inserter<\/code> &#8211; Whether visible in inserter (default: true)<\/li><li><code>source<\/code> &#8211; Origin of pattern (core, theme, plugin, pattern-directory)<\/li><\/ul><h3 class=\"wp-block-heading\">Pattern Categories<\/h3><p>Categories organize patterns in the inserter. WordPress registers these core categories:<\/p><figure class=\"wp-block-table\"><table><thead><tr><th>Category<\/th><th>Description<\/th><\/tr><\/thead><tbody><tr><td><code>banner<\/code><\/td><td>Bold sections for key content<\/td><\/tr><tr><td><code>buttons<\/code><\/td><td>Button and CTA patterns<\/td><\/tr><tr><td><code>columns<\/code><\/td><td>Multi-column layouts<\/td><\/tr><tr><td><code>text<\/code><\/td><td>Text-focused patterns<\/td><\/tr><tr><td><code>query<\/code> \/ <code>posts<\/code><\/td><td>Post display layouts<\/td><\/tr><tr><td><code>featured<\/code><\/td><td>Curated high-quality patterns<\/td><\/tr><tr><td><code>call-to-action<\/code><\/td><td>Conversion-focused sections<\/td><\/tr><tr><td><code>team<\/code><\/td><td>Team member displays<\/td><\/tr><tr><td><code>testimonials<\/code><\/td><td>Reviews and feedback<\/td><\/tr><tr><td><code>services<\/code><\/td><td>Service descriptions<\/td><\/tr><tr><td><code>contact<\/code><\/td><td>Contact information<\/td><\/tr><tr><td><code>about<\/code><\/td><td>Introduction sections<\/td><\/tr><tr><td><code>portfolio<\/code><\/td><td>Work showcases<\/td><\/tr><tr><td><code>gallery<\/code><\/td><td>Image layouts<\/td><\/tr><tr><td><code>media<\/code><\/td><td>Video\/audio layouts<\/td><\/tr><tr><td><code>videos<\/code><\/td><td>Video-specific layouts<\/td><\/tr><tr><td><code>audio<\/code><\/td><td>Audio-specific layouts<\/td><\/tr><tr><td><code>header<\/code><\/td><td>Site header designs<\/td><\/tr><tr><td><code>footer<\/code><\/td><td>Site footer designs<\/td><\/tr><\/tbody><\/table><\/figure><h3 class=\"wp-block-heading\">Pattern Sources<\/h3><p>WordPress loads patterns from multiple sources:<\/p><ol class=\"wp-block-list\"><li><strong>Core Patterns<\/strong> &#8211; Built into WordPress (<code>wp-includes\/block-patterns\/<\/code>)<\/li><li><strong>Theme Patterns<\/strong> &#8211; From theme&#8217;s <code>patterns\/<\/code> directory<\/li><li><strong>Plugin Patterns<\/strong> &#8211; Registered programmatically<\/li><li><strong>Remote Patterns<\/strong> &#8211; From wordpress.org\/patterns (Pattern Directory)<\/li><li><strong>theme.json Patterns<\/strong> &#8211; Referenced by slug in theme.json<\/li><\/ol><h2 class=\"wp-block-heading\">Registration Flow<\/h2><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\"><\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code\"><code>\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502                        WordPress Init                            \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502                                                                  \u2502\n\u2502  1. Core Categories Registered                                   \u2502\n\u2502     \u2514\u2500\u25ba _register_core_block_patterns_and_categories()          \u2502\n\u2502                                                                  \u2502\n\u2502  2. Core Patterns Registered (if theme supports)                 \u2502\n\u2502     \u2514\u2500\u25ba query-standard-posts, query-grid-posts, etc.            \u2502\n\u2502                                                                  \u2502\n\u2502  3. Theme Patterns Registered                                    \u2502\n\u2502     \u2514\u2500\u25ba _register_theme_block_patterns()                         \u2502\n\u2502         \u2514\u2500\u25ba Scans theme\/patterns\/ directory                      \u2502\n\u2502         \u2514\u2500\u25ba Child theme overrides parent patterns                \u2502\n\u2502                                                                  \u2502\n\u2502  4. Remote Patterns Loaded (if enabled)                          \u2502\n\u2502     \u2514\u2500\u25ba _load_remote_block_patterns()                            \u2502\n\u2502     \u2514\u2500\u25ba _load_remote_featured_patterns()                         \u2502\n\u2502     \u2514\u2500\u25ba _register_remote_theme_patterns()                        \u2502\n\u2502                                                                  \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518<\/code><\/pre><\/div><h2 class=\"wp-block-heading\">Theme Pattern Files<\/h2><p>Themes can define patterns as PHP files in the <code>patterns\/<\/code> directory:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">php<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-php\"><code class=\"language-php\">&lt;?php\n\/**\n * Title: Hero Section\n * Slug: my-theme\/hero-section\n * Categories: banner, featured\n * Keywords: hero, header, intro\n * Block Types: core\/post-content\n * Post Types: page\n * Viewport Width: 1200\n * Inserter: yes\n *\/\n?&gt;\n&lt;!-- wp:cover {&quot;url&quot;:&quot;...&quot;} --&gt;\n&lt;div class=&quot;wp-block-cover&quot;&gt;\n    &lt;!-- wp:heading --&gt;\n    &lt;h2&gt;Welcome&lt;\/h2&gt;\n    &lt;!-- \/wp:heading --&gt;\n&lt;\/div&gt;\n&lt;!-- \/wp:cover --&gt;<\/code><\/pre><\/div><p><strong>File Header Fields:<\/strong><\/p><ul class=\"wp-block-list\"><li><code>Title<\/code> &#8211; Pattern title (required)<\/li><li><code>Slug<\/code> &#8211; Unique pattern name (required)<\/li><li><code>Categories<\/code> &#8211; Comma-separated category slugs<\/li><li><code>Keywords<\/code> &#8211; Comma-separated search terms<\/li><li><code>Block Types<\/code> &#8211; Comma-separated block types<\/li><li><code>Post Types<\/code> &#8211; Comma-separated post type restrictions<\/li><li><code>Template Types<\/code> &#8211; Comma-separated template types<\/li><li><code>Viewport Width<\/code> &#8211; Integer width for preview<\/li><li><code>Inserter<\/code> &#8211; <code>yes<\/code> or <code>no<\/code><\/li><\/ul><h2 class=\"wp-block-heading\">Core Block Patterns<\/h2><p>WordPress ships with query-focused patterns:<\/p><figure class=\"wp-block-table\"><table><thead><tr><th>Pattern<\/th><th>Description<\/th><\/tr><\/thead><tbody><tr><td><code>core\/query-standard-posts<\/code><\/td><td>Basic post list with title, image, excerpt<\/td><\/tr><tr><td><code>core\/query-medium-posts<\/code><\/td><td>Medium-sized post layout<\/td><\/tr><tr><td><code>core\/query-small-posts<\/code><\/td><td>Compact post listing<\/td><\/tr><tr><td><code>core\/query-grid-posts<\/code><\/td><td>Grid layout for posts<\/td><\/tr><tr><td><code>core\/query-large-title-posts<\/code><\/td><td>Large title emphasis<\/td><\/tr><tr><td><code>core\/query-offset-posts<\/code><\/td><td>Offset\/featured first post layout<\/td><\/tr><\/tbody><\/table><\/figure><h2 class=\"wp-block-heading\">Theme Support<\/h2><p>Themes control core pattern loading:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">php<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-php\"><code class=\"language-php\">\/\/ Enable core patterns (default)\nadd_theme_support( &#039;core-block-patterns&#039; );\n\n\/\/ Disable core patterns\nremove_theme_support( &#039;core-block-patterns&#039; );<\/code><\/pre><\/div><h2 class=\"wp-block-heading\">Pattern Directory Integration<\/h2><p>Themes can reference patterns from wordpress.org\/patterns in theme.json:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">json<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-json\"><code class=\"language-json\">{\n    &quot;patterns&quot;: [\n        &quot;short-text-surrounded-by-round-images&quot;,\n        &quot;partner-logos&quot;\n    ]\n}<\/code><\/pre><\/div><p>These patterns are fetched via the REST API and cached.<\/p><h2 class=\"wp-block-heading\">Block Hooks Integration<\/h2><p>Since WordPress 6.5, pattern content is processed through the Block Hooks system:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">php<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-php\"><code class=\"language-php\">$content = apply_block_hooks_to_content(\n    $content,\n    $pattern,\n    &#039;insert_hooked_blocks_and_set_ignored_hooked_blocks_metadata&#039;\n);<\/code><\/pre><\/div><p>This allows hooked blocks to be inserted into pattern content automatically.<\/p><h2 class=\"wp-block-heading\">Best Practices<\/h2><h3 class=\"wp-block-heading\">Pattern Naming<\/h3><ul class=\"wp-block-list\"><li>Use namespace prefix: <code>theme-slug\/pattern-name<\/code> or <code>plugin-slug\/pattern-name<\/code><\/li><li>Use lowercase with hyphens<\/li><li>Be descriptive: <code>theme\/hero-with-cta<\/code> not <code>theme\/pattern-1<\/code><\/li><\/ul><h3 class=\"wp-block-heading\">Pattern Content<\/h3><ul class=\"wp-block-list\"><li>Use semantic HTML structure<\/li><li>Include placeholder content users will replace<\/li><li>Use theme-aware values where possible (colors, fonts)<\/li><li>Test with different content lengths<\/li><\/ul><h3 class=\"wp-block-heading\">Performance<\/h3><ul class=\"wp-block-list\"><li>Use <code>filePath<\/code> for lazy loading large patterns<\/li><li>Patterns in <code>patterns\/<\/code> directory are auto-cached<\/li><li>Remote patterns are cached via transients<\/li><\/ul><h3 class=\"wp-block-heading\">Accessibility<\/h3><ul class=\"wp-block-list\"><li>Include proper heading hierarchy<\/li><li>Use meaningful alt text in placeholder images<\/li><li>Ensure color contrast meets WCAG standards<\/li><\/ul><h2 class=\"wp-block-heading\">Version History<\/h2><figure class=\"wp-block-table\"><table><thead><tr><th>Version<\/th><th>Changes<\/th><\/tr><\/thead><tbody><tr><td>5.5.0<\/td><td>Block Patterns API introduced<\/td><\/tr><tr><td>5.8.0<\/td><td><code>blockTypes<\/code> property added<\/td><\/tr><tr><td>5.9.0<\/td><td>Pattern Directory integration<\/td><\/tr><tr><td>6.0.0<\/td><td>Theme patterns from <code>patterns\/<\/code> directory<\/td><\/tr><tr><td>6.1.0<\/td><td><code>postTypes<\/code> property added<\/td><\/tr><tr><td>6.2.0<\/td><td><code>templateTypes<\/code> property added<\/td><\/tr><tr><td>6.3.0<\/td><td>Pattern <code>source<\/code> tracking added<\/td><\/tr><tr><td>6.4.0<\/td><td><code>WP_Theme::get_block_patterns()<\/code> method<\/td><\/tr><tr><td>6.5.0<\/td><td><code>filePath<\/code> property for lazy loading<\/td><\/tr><\/tbody><\/table><\/figure><h2 class=\"wp-block-heading\">Related APIs<\/h2><ul class=\"wp-block-list\"><li><a href=\"https:\/\/chubes.net\/docs\/wordpress-core\/block-patterns\/wp_block_patterns_registry\/\">WP_Block_Patterns_Registry<\/a> &#8211; Pattern registry class<\/li><li><a href=\"https:\/\/chubes.net\/docs\/wordpress-core\/block-patterns\/wp_block_pattern_categories_registry\/\">WP_Block_Pattern_Categories_Registry<\/a> &#8211; Category registry<\/li><li><a href=\"https:\/\/chubes.net\/docs\/wordpress-core\/block-patterns\/block-pattern-functions\/\">Pattern Functions<\/a> &#8211; Registration functions<\/li><li><a href=\"https:\/\/chubes.net\/docs\/wordpress-core\/block-patterns\/block-patterns-hooks\/\">Pattern Hooks<\/a> &#8211; Available filters and actions<\/li><\/ul>","protected":false},"excerpt":{"rendered":"<p>Block patterns are predefined block layouts that users can insert into content with a single click. Introduced in WordPress 5.5, patterns provide reusable design templates ranging from simple text layouts&#8230;<\/p>\n","protected":false},"featured_media":0,"template":"","meta":{"footnotes":""},"tags":[],"project":[601],"project_type":[749],"class_list":["post-5523","documentation","type-documentation","status-publish","hentry","project-block-patterns","project_type-wordpress-reference"],"project_info":{"id":589,"name":"WordPress Core","slug":"wordpress-core"},"project_type_info":{"id":749,"name":"WordPress Reference","slug":"wordpress-reference"},"_links":{"self":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/5523","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation"}],"about":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/types\/documentation"}],"version-history":[{"count":3,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/5523\/revisions"}],"predecessor-version":[{"id":8994,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/5523\/revisions\/8994"}],"wp:attachment":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/media?parent=5523"}],"wp:term":[{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/tags?post=5523"},{"taxonomy":"project","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/project?post=5523"},{"taxonomy":"project_type","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/project_type?post=5523"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}