Theme Patterns

On every request, WordPress runs _register_theme_block_patterns() on init. It asks the active theme, and its parent when the theme is a child theme, for the list of pattern files, and registers each one in the WP_Block_Patterns_Registry singleton, next to core’s patterns, Pattern Directory patterns and patterns registered in code. Several details of that path explain most surprises:

The lumen theme ships six files in patterns/: hero.php (a cover with translatable strings and a theme image), page-about.php (starter content for new pages), query-book-grid.php (a block-type pattern for core/query), template-front-page.php (the body of templates/front-page.html), submissions-callout.php (a locked, content-only section) and book-spotlight.php (overridable markup for a synced pattern). functions.php registers the category lumen/house and one more pattern, lumen/footer-colophon; the hero image lives in assets/images/hero.webp. The rest of the theme is described in Themes Overview and Templates and Template Parts.

A pattern file starts with a PHP docblock whose Field: value lines describe the pattern. Title and Slug are required; a file without either is skipped with a "called incorrectly" notice. The other headers are optional.

Comma-separated values are split with wp_parse_list(); Viewport Width is cast to an integer; Inserter is true only for yes or true (and defaults to shown when the header is absent). An invalid slug produces a notice but, in 7.1.3, the pattern is still registered; fix it anyway, because every wp:pattern reference repeats the slug.

Pattern files are PHP, so they can call translation functions, build URLs and loop over arrays. The PHP runs once, when the registry first needs the content, and its output is stored as block markup. It therefore runs without the main query: conditionals such as is_page(), template tags such as the_title(), and checks on the current user or post return nothing useful. Data that must change per page belongs in blocks that render dynamically (Query Loop, post blocks) or in block bindings (see Block Bindings API), not in pattern PHP.

The lumen hero translates every visible string, escapes it for its context and points the cover image at a file in the theme with get_theme_file_uri(), which also lets a child theme replace the image by shipping the same path:

Source: Theme Handbook: Using PHP in Patterns

Rules that keep pattern PHP safe and valid:

Pattern titles and descriptions are translated by core at registration with the contexts "Pattern title" and "Pattern description"; the strings in the body are ordinary __() calls. wp i18n make-pot picks up both:

Source: WP-CLI Commands: wp i18n make-pot

The grep shows the entry #: patterns/hero.php, msgctxt "Pattern title", msgid "Hero with cover image", next to the body strings with their line numbers.

Loading the translations and translating themes in general is covered in Internationalization.

Core registers about twenty categories (banner, buttons, call-to-action, columns, featured, footer, gallery, header, media, posts, query, text, about, contact and others) regardless of whether core’s own patterns are loaded. A theme can add its own with register_block_pattern_category() on init. The slug may contain a /, which is a convenient way to namespace it; the label and description are translatable. lumen keeps all its patterns in one Lumen Press category so site owners find them first, and also lists them in core categories where they fit. The same functions.php registers the one pattern that is defined in PHP rather than a file (described in the next section):

Source: Theme Handbook: Registering Patterns

A category with no patterns is not shown in the inserter. unregister_block_pattern_category() removes a category, core’s included. User pattern categories created in the admin are terms of the wp_pattern_category taxonomy and are a different mechanism (see Patterns for Site Builders).

register_block_pattern( $pattern_name, $pattern_properties ) (5.5) is the PHP API behind the folder: the folder loader calls it with the parsed headers. Called directly, it takes the same properties in camelCase (blockTypes, postTypes, templateTypes, viewportWidth) with arrays instead of comma lists, plus either content (a string of block markup) or, since 6.5, filePath. It returns false and raises a notice when the name is not a string, when title is missing, or when neither content nor filePath is given. source is informational; theme is the value for theme code. A pattern must be registered once, by the folder or by code, not both.

Registering in code is the right choice when the markup is generated (the colophon above computes the year at registration), when a pattern is conditional (registered only when lumen-catalog is active, for example), or when a plugin ships the pattern. Everything else is easier to maintain as a file. Registration belongs on init. Older code registered patterns on admin_init or current_screen; the registry still tracks those so the post editor page can receive them, but the block-patterns REST endpoint the Site Editor uses never runs those actions and does not list them.

WordPress 7.0 added no new pattern registration API; its "PHP-only" feature concerns blocks: a block registered with register_block_type(), a render_callback and the autoRegister support appears in the editor without any JavaScript (see block.json and Registration). For patterns, register_block_pattern() and the /patterns folder remain the only APIs in 7.0 and 7.1.

Three switches remove patterns that other code registered. remove_theme_support( 'core-block-patterns' ) on after_setup_theme drops core’s bundled patterns and the "core" patterns of the Pattern Directory. Returning false from the should_load_remote_block_patterns filter stops every Pattern Directory request. unregister_block_pattern( 'slug' ) on init at priority 20 or later removes one pattern, for example a parent theme’s pattern in a child theme. lumen uses the first two (last lines above). The top-level patterns array of theme.json (6.0) is the opposite switch: it lists Pattern Directory slugs to show next to the theme’s own, and the filter disables it too.

A pattern with Block Types: core/post-content is offered as starter content. When a user creates a page, the editor opens a dialog with the patterns whose Post Types include page (or that list no post types); choosing one fills the page. Starter patterns have existed since 6.0, and Post Types was added in 6.1 to keep page layouts out of the dialog for posts and custom post types. They are post content, so they must not contain a site header or footer.

Source: Theme Handbook: Starter Patterns

The list is built from an array in PHP, which keeps the strings translatable without repeating the block markup. The last line includes another pattern; the REST endpoint that feeds the inserter (/wp/v2/block-patterns/patterns) resolves it to blocks and returns the headers as block_types: ["core/post-content"] and post_types: ["page"].

A starter template pattern works the same way for the Site Editor: a pattern with Template Types is offered in the "Choose a pattern" dialog when a site owner adds a template of that type. Setting Inserter: no keeps a full-page layout out of the post editor’s inserter.

Block Types with any other block name turns a pattern into an alternative layout for that block. The editor shows it where the block offers patterns:

The Lumen book grid is a Query Loop of lp_book posts in a three-column grid. It sets "inherit":false so that it always lists books, whatever the template’s main query is:

Source: Theme Handbook: Block Type Patterns

The pattern names the post type, but it does not register it: post types are plugin territory, and lumen-catalog registers lp_book. Without the plugin the grid renders its "no results" paragraph. The colophon registered in functions.php is a block-type pattern for core/template-part/footer, offered when the site owner replaces the footer.

A template or template part can include a pattern with the Pattern block, <!-- wp:pattern {"slug":"lumen/hero"} /-->. The block (core/pattern, since 5.9) has no inserter entry; it exists for theme files. It is the way to use translatable strings and theme URLs in templates, which are plain HTML files and cannot run PHP. lumen keeps the front page template minimal and puts its body in a pattern with Template Types and Inserter: no:

Source: Theme Handbook: Usage in Templates

Source: Theme Handbook: Starter Patterns

What happens to a wp:pattern block depends on where it is read:

Block markup can carry two locking attributes. lock (5.9) applies to the block itself; templateLock applies to the children of a container block (Group, Cover, Columns, Column, Navigation and blocks that declare the attribute):

The Lumen submissions box combines both: the group cannot be moved or removed, and inside it only text and the link change.

Source: Theme Handbook: Patterns and Block Locking

Locks are guidance for the editing interface, not permissions. Any user who can edit the post can unlock a block from its toolbar unless the site restricts that with the canLockBlocks editor setting (filter block_editor_settings_all), and the stored markup can always be changed through the code editor or the REST API.

Since 7.0, every unsynced pattern inserted from the inserter, and every single-root pattern resolved from a template, is edited in content-only mode by default even without templateLock. An explicit "templateLock":"contentOnly" still matters: it survives the site-wide opt-out (disableContentOnlyForUnsyncedPatterns) and it also locks the section on sites still running 6.9. Content-only mode only exposes attributes that a block declares with "role": "content" in block.json, so a custom block without that role cannot be edited there. The Buttons, List, Social Icons and Navigation blocks received specific content-only behaviour in 7.0 and are worth checking in every pattern that uses them.

Theme patterns are never synced: inserting one copies its blocks. Pattern overrides (6.6) only work inside a synced pattern, a wp_block post that a site owner creates. A theme can still prepare a pattern for overrides by shipping the binding metadata that the editor’s Enable overrides button would write. When a site owner inserts the theme pattern and turns it into a synced pattern (Create pattern, synced), the override slots are already defined:

Source: WordPress Developer Blog: An introduction to overrides in Synced Patterns

Each overridable block needs a metadata.name that is unique inside the pattern, because it keys the per-page values, and a __default binding to the core/pattern-overrides source, which covers every attribute the block supports for bindings (content for headings and paragraphs; url, text, linkTarget and rel for buttons; the image attributes for images). Since 7.0 a custom block can take part by declaring its attributes through the block_bindings_supported_attributes filter. Override names are user-facing in the editor’s sidebar, so they should be readable words; they are not translated.

To check the markup, a test run stored the pattern’s content as a wp_block post (ID 8) and created a page whose content is <!-- wp:block {"ref":8,"content":{"Book title":{"content":"The Glass Orchard"},...}} /-->, the form the editor saves for an instance with overrides. https://lumenpress.test/spring-catalogue/ then renders the per-page values inside the theme’s layout:

How site owners store and edit instance values is described in Patterns for Site Builders. A theme must not create wp_block posts itself: content creation is plugin territory.

The checks below run against a site with lumen and lumen-catalog active and three published books, such as the stack in Local Development Environments. The first lists what the registry holds for the theme:

Source: WP-CLI Commands: wp eval

Seven is the whole registry: remove_theme_support( 'core-block-patterns' ) and the should_load_remote_block_patterns filter leave no core or directory patterns. A single entry printed with var_export() before anything has asked for its content still carries 'filePath' => '/var/www/html/wp-content/themes/lumen/patterns/hero.php' instead of markup. The front page, fetched with curl -s https://lumenpress.test/, renders the hero, the heading, the three books from the Query Loop and the submissions box in place inside <main>, with every string and URL from the pattern PHP filled in (src="https://lumenpress.test/wp-content/themes/lumen/assets/images/hero.webp", href="https://lumenpress.test/books/").

The rendered HTML carries no trace of the locks or of the pattern names: they are editor attributes in the block comments. They do appear in what the Site Editor loads. Requesting the template through REST as an administrator (/wp/v2/templates/lumen//front-page?context=edit) and printing the attributes of the blocks inside <main> gives:

The middle group, written directly in lumen/template-front-page, has no pattern metadata; its nested Query Loop has "patternName":"lumen/query-book-grid". The pattern’s title replaced the group’s own metadata.name, because pattern metadata takes precedence over the block’s.

Because parsed headers are cached per theme version, a new pattern file is not registered until one of these happens: the Version in style.css changes, the 30-minute transient expires, the transient is deleted, or the site runs in theme development mode. On the test site, adding patterns/events-list.php left it unregistered until the transient was deleted:

Source: WP-CLI Commands: wp transient delete

During theme development, define( 'WP_DEVELOPMENT_MODE', 'theme' ); in wp-config.php disables the cache (and the theme.json caches) so every request rescans the folder; with WP_DEBUG on, header errors then appear at once, such as Function get_block_patterns was called incorrectly. Could not register file ".../patterns/no-title.php" as a block pattern ("Title" field missing).

Development mode must not be enabled in production (see wp-config.php Reference). For releases, bumping the theme version is the reliable way to invalidate the cache, and a persistent object cache (Redis) stores the transient there instead of in wp_options.

None of the three older books teaches theme patterns. Pro WordPress treats only classic themes, where reusable sections are widgets, PHP template parts or shortcodes; in a block theme they are pattern files and template parts. WordPress All-in-One For Dummies covers patterns only from the editor. Ultimate WordPress Handbook still says "reusable blocks" (synced patterns since 6.3) and calls full site editing still maturing, although the /patterns API has been stable since 6.0. None covers overrides (6.6), filePath loading (6.5) or the 7.0 content-only default.