What Are Block Patterns?
Think of block patterns as templates within the editor. Instead of assembling a hero section from scratch every time (adding a cover block, then a heading, then a paragraph, then buttons) you insert a pre-built pattern and tweak the content. WordPress 5.5 introduced them, and they've gotten better with every release since.
Patterns differ from reusable blocks in a key way: when you insert a pattern, you get a fresh copy. Changes to one instance don't affect others. Reusable blocks stay synced across every place they're used.
Registering Your First Pattern
You register block patterns in your theme's functions.php file (or a dedicated patterns file). The register_block_pattern() function takes a name and an array of properties:
register_block_pattern(
'mytheme/hero-section',
array(
'title' => 'Hero Section',
'description' => 'Full-width hero with heading and CTA',
'categories' => array('featured'),
'content' => '<!-- wp:cover ... -->...',
)
);The content property holds the block markup. The easiest way to generate it: build the layout in the block editor, switch to Code view, and copy the markup. According to the WordPress Block Pattern documentation, this approach ensures valid block grammar.
Organizing Patterns with Categories
WordPress ships with default pattern categories (Text, Gallery, Header, etc.), but you can register custom ones:
register_block_pattern_category(
'mytheme-sections',
array('label' => 'Theme Sections')
);Grouping patterns into logical categories helps users find them quickly, especially in themes with dozens of patterns.
Pattern Best Practices
Keep Content Generic
Use placeholder text and images that clearly need replacing. Avoid highly specific content that might confuse users. Headings like "Your Headline Here" are fine. They signal that customization is expected.
Use Theme Variables
Reference your theme's color palette and font sizes instead of hardcoding values. This ensures patterns adapt when users change theme settings. WordPress provides has-primary-color, has-large-font-size and similar utility classes.
Test Across Viewports
Every pattern should look good on mobile, tablet, and desktop. The block editor's responsive preview helps, but test on actual devices when possible. Patterns with multi-column layouts need particular attention.
Consider Performance
Patterns with heavy imagery should use lazy loading. Keep the block count reasonable. A pattern with 50 nested blocks slows down the editor. If a pattern is too complex, split it into smaller, composable pieces.
File-Based Patterns (WordPress 6.0+)
Since WordPress 6.0, you can define patterns as PHP files in a /patterns directory in your theme. Each file includes a header comment with pattern metadata:
<?php
/**
* Title: Hero Section
* Slug: mytheme/hero-section
* Categories: featured
*/
?>
<!-- wp:cover ... -->
...This approach keeps your functions.php clean and makes patterns easier to manage. WordPress automatically registers them when it finds the /patterns directory.
Locking Patterns to Protect Structure
Once a pattern is inserted, users can technically delete, move, or rearrange every block inside it, which is not always what you want for something like a header or a carefully balanced pricing table. Gutenberg's block locking API lets you restrict specific behaviors without freezing the pattern completely. You can lock movement while still allowing content edits, or lock removal so a required legal disclaimer block cannot be deleted by accident.
<!-- wp:group {"lock":{"move":true,"remove":true}} -->
...
<!-- /wp:group -->Apply locking sparingly. Locking every block in every pattern defeats the purpose of giving users an editable starting point, and frustrated users who cannot make basic edits will abandon the pattern entirely and rebuild the section from scratch, which is the outcome you were trying to avoid in the first place.
Debugging Patterns That Won't Register
The most common reason a registered pattern fails to appear in the inserter is a namespace collision, two patterns sharing the same slug, often because a plugin and a theme both use a generic name like hero-section without a unique prefix. Always namespace your pattern slugs with your theme or plugin name, as shown in the examples above.
The second most common issue is invalid block markup in the content property. A single unescaped quote or a manually edited HTML comment can break the block grammar WordPress relies on to parse the pattern. If a pattern silently fails to register, paste the content through the block editor's Code view first to confirm it parses cleanly before wiring it into register_block_pattern().
Real-World Pattern Ideas
Patterns that save users the most time:
- Hero sections, Full-width backgrounds with centered text and CTAs
- Testimonial grids, Quote blocks arranged in columns with author details
- Pricing tables, Side-by-side plan comparisons with feature lists
- Team profiles: Photo, name, role, and social links in a grid
- FAQ accordions: Collapsible question-answer pairs
- CTA banners: Gradient backgrounds with buttons and urgency text
The best patterns solve real problems your users face repeatedly. Pay attention to support tickets and forum questions. They'll tell you exactly which layouts people struggle to build.