Views: 1
Block Patterns allow theme developers to define reusable, pre-designed block layouts that users can quickly insert into pages or templates. They make theme building more modular, efficient, and user-friendly.
Block Patterns are one of the most powerful features of block themes — they let you design and save reusable sections of content (hero sections, feature grids, testimonials, footers, etc.) that users can insert anywhere with a single click.
What You’ll Learn?
- What Block Patterns are and how they work?
- How to create pattern files in your block theme?
- How to register patterns using
register_block_pattern()? - How to categorize patterns using
register_block_pattern_category()? - How to use patterns inside templates and template parts?
- How to display patterns in the Site Editor?
Step 1: What Are Block Patterns?
Block Patterns are predefined block layouts that can be easily inserted into posts, pages, or templates.
They are stored as HTML block markup, just like your template files, and registered with metadata so that WordPress recognizes them.
Example Use Cases
- Hero section
- Call-to-action area
- Testimonials
- Pricing tables
- Newsletter signup
Step 2: Create the patterns Folder
Inside your Versana theme, create a new directory:
/wp-content/themes/versana/patterns/
This is where all your pattern files will live.
🧱 Step 3: Create Your First Pattern File
Let’s create a simple Hero Section pattern.
Create a new file:/patterns/hero-banner.php
And add this content:
<?php
/**
* Title: Hero Banner
* Slug: versana/hero-banner
* Categories: versana-sections, featured
* Keywords: hero, banner, cover
* Block Types: core/cover
* Description: A large hero section with background image and heading.
*/
?>
<!-- wp:cover {"url":"<?php echo esc_url( get_template_directory_uri() . '/assets/images/hero.jpg' ); ?>","dimRatio":40,"minHeight":500,"align":"full","className":"hero-banner"} -->
<div class="wp-block-cover alignfull hero-banner" style="min-height:500px">
<span class="wp-block-cover__background has-background-dim"></span>
<img class="wp-block-cover__image-background" src="<?php echo esc_url( get_template_directory_uri() . '/assets/images/hero.jpg' ); ?>" alt="" />
<div class="wp-block-cover__inner-container">
<!-- wp:heading {"textAlign":"center","level":1} -->
<h1 class="has-text-align-center">Welcome to Versana</h1>
<!-- /wp:heading -->
<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">A beautiful, modern WordPress block theme for creative professionals.</p>
<!-- /wp:paragraph -->
<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
<div class="wp-block-buttons">
<!-- wp:button {"backgroundColor":"primary","textColor":"background","className":"cta-button"} -->
<div class="wp-block-button cta-button">
<a class="wp-block-button__link has-background-color has-primary-background-color">Get Started</a>
</div>
<!-- /wp:button -->
</div>
<!-- /wp:buttons -->
</div>
</div>
<!-- /wp:cover -->Understanding Each Line
Pattern Header (PHP DocBlock):
/**
* Title: Hero Banner
* Slug: versana/hero-banner
* Categories: versana-sections, featured
* Keywords: hero, banner, cover
* Block Types: core/cover
* Description: A large hero section with background image and heading.
*/This metadata tells WordPress how to identify the pattern:
| Field | Purpose |
|---|---|
| Title | The human-readable title shown in the editor |
| Slug | Unique identifier (theme-slug/pattern-name) |
| Categories | Determines where it appears in the pattern inserter |
| Keywords | Helps users find it via search |
| Block Types | Optional — restricts which blocks it can be inserted into |
| Description | Brief info shown in the editor panel |
Pattern Content:
The block HTML markup defines what the pattern will render.
It can include any valid Gutenberg blocks (Cover, Heading, Buttons, etc.).
Attributes like:
"url": Background image URL"dimRatio": Overlay opacity"minHeight": Section height"align": Alignment (full, wide, none)"className": Custom CSS for styling
Step 4: Register Your Pattern Category
Create a new file in your theme (if it doesn’t exist yet):functions.php
Add this code:
add_action( 'init', 'versana_register_pattern_categories' );
function versana_register_pattern_categories() {
register_block_pattern_category(
'versana-sections',
array( 'label' => __( 'Versana Sections', 'versana' ) )
);
}Explanation
This code registers a custom pattern category named “Versana Sections” which appears as a section in the pattern inserter under “Patterns → Versana Sections”.
Step 5: Register Your Pattern (Optional)
WordPress automatically loads all .php pattern files in the /patterns folder.
But if you prefer to register manually, use:
add_action( 'init', 'versana_register_patterns' );
function versana_register_patterns() {
register_block_pattern(
'versana/hero-banner',
array(
'title' => __( 'Hero Banner', 'versana' ),
'description' => __( 'A large hero section with background image and heading.', 'versana' ),
'categories' => array( 'versana-sections' ),
'content' => file_get_contents( get_template_directory() . '/patterns/hero-banner.php' ),
)
);
}Step 6: Add More Patterns
You can create more files inside /patterns/:
| File Name | Purpose |
|---|---|
about-section.php | For About Us layout |
features-grid.php | For services/features section |
testimonials.php | For testimonials layout |
cta-section.php | For call-to-action areas |
Each follows the same header and block structure.
Step 7: Insert Patterns in the Site Editor
Once you’ve added your patterns, go to:
Dashboard → Appearance → Editor → Patterns → Versana Sections
You’ll now see all your registered patterns there.
Click “+” and insert them anywhere in your templates or pages.
Step 8: Use a Pattern Inside a Template
You can even include a pattern directly in your front-page.html or other template files using the special pattern block:
<!-- wp:pattern {"slug":"versana/hero-banner"} /-->This inserts your hero banner pattern automatically into the front page template.
Step 9: Style Your Patterns with CSS
In your style.css, add:
.hero-banner {
color: #fff;
text-align: center;
background-size: cover;
background-position: center;
}
.hero-banner .cta-button .wp-block-button__link {
padding: 14px 28px;
border-radius: 6px;
}Step 10: Test and Refine
Reload your Site Editor and ensure that:
- Your pattern shows in the pattern list
- It renders correctly when inserted
- All block attributes are functional
Bonus: Pattern Reusability Across Sites
Patterns from your theme are automatically exportable.
You can:
- Copy
.phpfiles into another theme’s/patterns/folder - Or package them as a pattern library plugin for others to use
💡 Developer Tips
| Tip | Description |
|---|---|
| 🏷️ Use unique slugs | Always prefix patterns with your theme name (versana/) |
| 🗂️ Group logically | Create multiple categories for better organization |
| 💅 Keep content neutral | Avoid hard-coded text that doesn’t fit all sites |
🌈 Use theme.json colors | So patterns adapt to global styles dynamically |
Conclusion
Block Patterns are essential for making your block theme user-friendly and flexible. They let anyone create consistent, reusable designs in seconds without coding — and they make your Block Theme professional and ready for public release.
