Block Editor: theme.json – Register Patterns

This content is marked source of information.

WordPress theme.json offers registeration of block patterns via theme.json. It reduces the complexity or workload of registering patterns in classic themes via functions.php. No matters your theme is classic build or based on full site editing concept, theme.json works for both builds nicely.

There are 3 steps to register or add patterns via theme.json: –

• Create patterns directory
• Add pattern file or files
• Add pattern slugs in theme.json

Step 1: Create a directory in theme root named as patterns.

Since WordPress 6.0 version, WP considers all valid PHP files having pattern header, just like plugin or page templates, in patterns directory as available patterns.

Step 2: Add your first pattern file inside patterns directory in the following manner and name it as something pattern-one.php

<?php
 /**
  * Title: Pattern Name
  * Slug: my-theme-specific-patterns/pattern-one
  * Categories: custom-registered-category, featured
  * Keywords: keyword1, another one, more
  * Inserter: true
  */
?>

<!-- Pattern Output Starts Here -->

In this example, I added a pattern containing 2 paragraph blocks wrapped by a group block. This is a simple pattern. Make a pattern of blocks and name your different patterns. For each new pattern that you need, create a separate file in patterns directory and note down the pattern slug that you define.

Block Pattern File Header Parameters

Follow these guidelines to define pattern file header: –

• Title: required – Name of the pattern.
• Slug: required – Unique id of this pattern. This will be used in theme.json.
• Categories: required – Names of block editor pattern categories where you want this pattern to appear in Inserter Panel. Either use existing categories such as featured or use your theme registered categories (if available). If not available, the pattern will be shown under Uncategorized category.
• Keywords: optional – add some keywords to search this pattern in inserter panel
• Inserter: optional – Add a Boolean value true to show it in the inserter panel or not. You can keep it false to use pattern programmatically somewhere.
• Block Types: optional – one or more block types separated by comma

Step 3: Add your pattern slug in theme.json in patterns (array of strings) following the below code. Patterns array is defined at top level. It is not nested under settings or styles or templateParts.

{
	"version": 2,
	   "patterns" : [
		   "my-theme-specific-patterns/pattern-one",
         "my-patterns/another-pattern"
	   ],
	"settings": {...},
    "styles": {...},
    "templateParts" : []
}