Block patterns are predefined arrangements of blocks that editors can insert into any post or page with a single click — they are to the block editor what shortcodes were to the Classic Editor: reusable, pre-styled layout starters that reduce repetitive work and enforce design consistency across a site. Patterns are registered with register_block_pattern(), which accepts a unique name (namespaced as myplugin/pattern-name), a title, an optional description and category, keywords for search, and the content string — a serialized block grammar string that is the same format stored in post content. The content string is typically authored by building the layout in the block editor, copying the code editor view, and pasting it into the PHP registration call. Block pattern categories group patterns in the inserter — custom categories are registered with register_block_pattern_category() and assigned to patterns via the categories property. Patterns can be registered from a file using register_block_patterns_from_directory() (introduced in WordPress 6.0) — each pattern is a PHP file in the designated directory that returns an array of pattern metadata and sets $content, keeping pattern code out of functions.php. The Pattern Directory (accessible at wordpress.org/patterns) provides community-contributed patterns that WordPress downloads and makes available in the inserter via the Patterns tab — themes can opt out of remote patterns with add_filter('should_load_remote_block_patterns', '__return_false') for privacy or performance reasons. Synced patterns (formerly Reusable Blocks) are patterns stored as CPT entries of type wp_block — editing a synced pattern updates every instance where it is used, analogous to a shared component. Non-synced patterns (the default from WordPress 6.3+) insert a copy that can be edited independently per instance. The InnerBlocks post covers building custom block types; block patterns cover composing existing blocks into reusable templates without writing JavaScript.

Problem: A theme for a marketing agency requires 8 recurring layout patterns — hero sections, testimonial grids, CTA banners, and pricing tables — that designers keep recreating from scratch in each new page, spending 20–30 minutes per page on layout work instead of content.

Solution: Register the 8 patterns using PHP register_block_pattern() calls, organize them into a custom “Agency” pattern category, and load pattern content from individual PHP files in a /patterns/ directory to keep the code organized and editable.

// functions.php — register pattern category and load all patterns from directory

add_action( 'init', 'agency_register_block_patterns' );

function agency_register_block_patterns(): void {
    // Register custom category
    register_block_pattern_category( 'agency', [
        'label'       => __( 'Agency', 'agency-theme' ),
        'description' => __( 'Layout patterns for agency marketing pages.', 'agency-theme' ),
    ] );

    // Register a specific pattern manually
    register_block_pattern( 'agency/hero-split', [
        'title'       => __( 'Hero — Split Image', 'agency-theme' ),
        'description' => __( 'Full-width hero with text on left and image on right.', 'agency-theme' ),
        'categories'  => [ 'agency', 'featured' ],
        'keywords'    => [ 'hero', 'banner', 'split', 'header' ],
        'blockTypes'  => [ 'core/cover' ],
        'content'     => agency_get_pattern_content( 'hero-split' ),
    ] );

    register_block_pattern( 'agency/testimonials-grid', [
        'title'      => __( 'Testimonials Grid', 'agency-theme' ),
        'categories' => [ 'agency' ],
        'keywords'   => [ 'testimonials', 'reviews', 'quotes', 'social proof' ],
        'content'    => agency_get_pattern_content( 'testimonials-grid' ),
    ] );
}

function agency_get_pattern_content( string $name ): string {
    $file = get_theme_file_path( "patterns/{$name}.php" );
    if ( ! file_exists( $file ) ) {
        return '';
    }
    ob_start();
    include $file;
    return ob_get_clean() ?: '';
}

// patterns/hero-split.php — pattern content file
// File-header comment auto-registers this pattern in WP 6.0+ themes:
/**
 * Title: Hero Split
 * Slug: agency/hero-split
 * Categories: agency, featured
 * Keywords: hero banner split header
 */
echo <<<'PATTERN'



    
    


        
        
Your tagline here
        

        
        
Compelling headline that converts
        

        
        
Supporting text that expands on the headline and communicates value in two or three sentences.
        

        
        

            
            
Get Started
            
        
        

    
    

    
    

        
        

            
        
        
    
    



PATTERN;

NOTE: WordPress 6.0+ automatically registers patterns from a theme’s /patterns/ directory when each PHP file includes a file-header comment block: /** * Title: My Pattern * Slug: mytheme/my-pattern * Categories: featured */ — this eliminates the need for manual register_block_pattern() calls for theme-bundled patterns. The file-header approach also means the pattern is registered only when the theme is active, and WordPress handles the registration timing correctly relative to the init hook. Use add_filter('should_load_remote_block_patterns', '__return_false') to disable downloading patterns from the WordPress.org Pattern Directory if your site has strict CSP or privacy requirements.