{"id":33092,"date":"2026-02-16T19:55:34","date_gmt":"2026-02-16T19:55:34","guid":{"rendered":"https:\/\/brndle.com\/?p=33092"},"modified":"2026-02-16T19:55:34","modified_gmt":"2026-02-16T19:55:34","slug":"custom-block-patterns-wordpress","status":"publish","type":"post","link":"https:\/\/brndle.com\/custom-block-patterns-wordpress\/","title":{"rendered":"How to Create Custom Block Patterns in WordPress Block Themes"},"content":{"rendered":"

Block patterns are one of the most powerful features in the WordPress block theme ecosystem. They are pre-built layouts made of blocks that you can insert with a single click \u2014 hero sections, pricing tables, testimonial grids, call-to-action bars, team member layouts, and anything else you can build with blocks. Instead of assembling the same layout manually every time, you build it once as a pattern and reuse it across your entire site.<\/p>\n\n

WordPress ships with dozens of default patterns, but the real power comes from creating your own. Custom patterns let you define your brand’s specific layouts, enforce design consistency across your site, and give content editors pre-approved sections they can drop into any page without touching the design.<\/p>\n\n

This guide covers everything: registering patterns in PHP, organizing them into categories, understanding synced vs unsynced patterns, creating patterns from the editor, and building advanced PHP-based dynamic patterns. If you are new to block themes, start with our complete theme.json configuration guide<\/a> first.<\/p>\n\n

What Block Patterns Are (and Are Not)<\/h2>\n\n

A block pattern is a collection of blocks arranged in a specific layout with predefined content, styles, and settings. When you insert a pattern into a page, WordPress copies all the blocks and their attributes into your content. From that point, you can edit the blocks individually \u2014 the pattern is just the starting point.<\/p>\n\n

Patterns are not<\/strong> reusable blocks (now called synced patterns). The difference matters:<\/p>\n\n

Feature<\/th>Regular Pattern (Unsynced)<\/th>Synced Pattern<\/th><\/tr><\/thead>
What happens on insert<\/td>Blocks are copied. Each instance is independent.<\/td>A reference is inserted. All instances share the same content.<\/td><\/tr>
Editing one instance<\/td>Only affects that instance<\/td>Changes appear everywhere the pattern is used<\/td><\/tr>
Best for<\/td>Starting layouts, templates, design systems<\/td>Shared content like CTAs, announcements, footer blocks<\/td><\/tr>
Stored as<\/td>PHP registration or wp_block<\/code> post type<\/td>wp_block<\/code> post type with wp_pattern_sync_status<\/code> meta<\/td><\/tr><\/tbody><\/table><\/figure>\n\n

Method 1: Register Patterns in PHP<\/h2>\n\n

The most reliable way to add custom patterns to your block theme is through PHP registration using the register_block_pattern()<\/code> function. This approach keeps patterns in your theme’s codebase, makes them version-controllable, and ensures they are available immediately on theme activation.<\/p>\n\n

Basic Pattern Registration<\/h3>\n\n
add_action( 'init', function() {\n    register_block_pattern(\n        'mytheme\/hero-with-cta',\n        array(\n            'title'       => __( 'Hero Section with CTA', 'mytheme' ),\n            'description' => __( 'A full-width hero section with heading, paragraph, and two buttons.', 'mytheme' ),\n            'categories'  => array( 'featured', 'banner' ),\n            'keywords'    => array( 'hero', 'banner', 'cta', 'landing' ),\n            'content'     => '\n
<\/span>
\n\n
Build Something Beautiful<\/h1>\n\n\n
Create stunning websites with the power of WordPress block themes.<\/p>\n\n\n
\n
Get Started<\/a><\/div>\n\n\n
Learn More<\/a><\/div>\n<\/div>\n\n<\/div><\/div>\n',\n        )\n    );\n});<\/code><\/pre>\n\n
Pattern Properties Explained<\/h3>\n\n
Property<\/th>Required<\/th>Purpose<\/th><\/tr><\/thead>
title<\/code><\/td>Yes<\/td>Display name in the pattern inserter<\/td><\/tr>
content<\/code><\/td>Yes<\/td>Block markup (copy from the editor’s Code Editor view)<\/td><\/tr>
description<\/code><\/td>No<\/td>Shown as a tooltip in the pattern inserter<\/td><\/tr>
categories<\/code><\/td>No<\/td>Array of category slugs for organization<\/td><\/tr>
keywords<\/code><\/td>No<\/td>Search terms to help users find the pattern<\/td><\/tr>
viewportWidth<\/code><\/td>No<\/td>Preview width in pixels (default: 800)<\/td><\/tr>
blockTypes<\/code><\/td>No<\/td>Suggest this pattern when specific blocks are inserted<\/td><\/tr>
inserter<\/code><\/td>No<\/td>Set to false<\/code> to hide from the inserter (for programmatic use only)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n
Method 2: File-Based Patterns (WordPress 6.0+)<\/h2>\n\n
Since WordPress 6.0, you can register patterns by simply creating PHP files in your theme’s patterns\/<\/code> directory. WordPress automatically discovers and registers them \u2014 no register_block_pattern()<\/code> call needed.<\/p>\n\n
Create the Pattern File<\/h3>\n\n
Create a file at patterns\/hero-cta.php<\/code> in your theme:<\/p>\n\n
<?php\n\/**\n * Title: Hero Section with CTA\n * Slug: mytheme\/hero-cta\n * Categories: featured, banner\n * Keywords: hero, banner, cta, landing\n * Viewport Width: 1200\n *\/\n?>\n<!-- wp:cover {\"dimRatio\":60,\"overlayColor\":\"black\",\"isUserOverlayColor\":true,\"align\":\"full\"} -->\n<div class=\"wp-block-cover alignfull\">\n  <span class=\"wp-block-cover__background has-black-background-color has-background-dim-60 has-background-dim\"><\/span>\n  <div class=\"wp-block-cover__inner-container\">\n    <!-- wp:heading {\"textAlign\":\"center\",\"level\":1} -->\n    <h1 class=\"wp-block-heading has-text-align-center\">Build Something Beautiful<\/h1>\n    <!-- \/wp:heading -->\n    <!-- wp:paragraph {\"align\":\"center\"} -->\n    <p class=\"has-text-align-center\">Create stunning websites with WordPress block themes.<\/p>\n    <!-- \/wp:paragraph -->\n  <\/div>\n<\/div>\n<!-- \/wp:cover --><\/code><\/pre>\n\n
The PHP comment block at the top is the pattern header. WordPress reads these comments to register the pattern automatically. The Slug<\/code> must be unique and should follow the themename\/pattern-name<\/code> convention.<\/p>\n\n
This method is cleaner than PHP registration for most use cases. Your pattern content lives in its own file, it is easy to read and edit, and you do not need any registration code.<\/p>\n\n
Creating Pattern Categories<\/h2>\n\n
Custom categories help organize your patterns in the inserter. Register them using register_block_pattern_category()<\/code>:<\/p>\n\n
add_action( 'init', function() {\n    register_block_pattern_category(\n        'mytheme-heroes',\n        array(\n            'label' => __( 'Hero Sections', 'mytheme' ),\n        )\n    );\n\n    register_block_pattern_category(\n        'mytheme-testimonials',\n        array(\n            'label' => __( 'Testimonials', 'mytheme' ),\n        )\n    );\n\n    register_block_pattern_category(\n        'mytheme-pricing',\n        array(\n            'label' => __( 'Pricing Tables', 'mytheme' ),\n        )\n    );\n});<\/code><\/pre>\n\n
Then assign patterns to these categories using the categories<\/code> property in either the PHP registration or the file header comment.<\/p>\n\n
How to Get Block Markup for Patterns<\/h2>\n\n
The hardest part of creating patterns is getting the correct block markup. Here is the most reliable workflow:<\/p>\n\n
    \n
  1. Design the layout visually<\/strong> in the WordPress block editor. Add blocks, adjust settings, apply colors, set spacing \u2014 everything you want in the pattern<\/li>\n
  2. Switch to the Code Editor<\/strong> by clicking the three-dot menu in the top-right corner of the editor and selecting “Code editor”<\/li>\n
  3. Copy the entire block markup<\/strong> \u2014 this is what goes into the content<\/code> property of your pattern<\/li>\n
  4. Paste it into your pattern file<\/strong> (either the PHP registration or the patterns\/<\/code> file)<\/li>\n
  5. Replace specific content with placeholders<\/strong> \u2014 change “Our Company” to “Your Heading Here” so editors know what to customize<\/li>\n<\/ol>\n\n
    This visual-first approach ensures your block markup is always valid. Writing block comments by hand is error-prone and unnecessary when the editor generates correct markup for you.<\/p>\n\n
    Synced Patterns: Shared Content Across Your Site<\/h2>\n\n
    Synced patterns (formerly called reusable blocks) are different from regular patterns. When you edit a synced pattern, the changes appear everywhere that pattern is used. This is ideal for content that needs to stay consistent across your site:<\/p>\n\n