Kinds of pattern

Two questions describe any pattern in WordPress. Where does it live: in a file in the theme, or in the database? And when someone inserts it, does the copy stay linked to the original, or go its own way? Pattern Builder manages all four combinations and moves patterns between them.

Theme patterns and user patterns

A theme pattern is a PHP file in the theme’s patterns directory. A comment header at the top carries its metadata and the block markup follows:

<?php
/**
 * Title: Pricing Plans
 * Slug: my-theme/pricing-plans
 * Description: Two plans side by side.
 * Categories: my-theme_sections, call-to-action
 * Keywords: pricing, plans
 * Viewport Width: 1400
 */
?>
<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">…</div>
<!-- /wp:group -->

Theme patterns are versioned with the theme, ship wherever the theme ships, and are identified by their namespaced slug. Pattern Builder reads them from the child and parent theme, edits them in place, and writes changes straight back to the file. Nothing is copied into the database, so the file in git is always the truth.

A user pattern is a wp_block post in the database, the kind WordPress creates when you select some blocks in the editor and choose Create Pattern. Its title and description are post fields and it has no header at all. User patterns belong to one site; they are quick to make and easy to change, and they travel only by export.

	Theme pattern	User pattern
Stored as	A PHP file in patterns/	A wp_block post
Identified by	Namespaced slug, e.g. my-theme/hero	Post ID
Metadata	File header: categories, keywords, block types, post types, template types, viewport width, inserter, synced	Title, description, categories, and synced status as post meta
Travels with	The theme	The site, or an export
Can be a starter pattern	Yes	No: the headers that place a starter pattern have nowhere to go

Converting between them

The Pattern Source panel offers Convert to Theme Pattern on a user pattern and Convert to User Pattern on a theme pattern. Conversion moves the pattern and its images together: a user pattern becoming a theme file has its images copied into the theme’s assets/images directory and its markup rewritten to reference them, so the theme is self-contained; a theme pattern becoming a user pattern has its images imported into the media library and the attachment IDs written into the blocks, so the editor treats them as its own.

A common workflow is to design in the editor as a user pattern, then convert to a theme pattern once it is right, so it ships with the theme and lives in version control.

Synced and unsynced patterns

An unsynced pattern is a starting point. Inserting it copies the blocks into the page, and from then on the copy is ordinary content: edit anything, and changing the pattern later affects only new insertions. Most patterns are unsynced.

A synced pattern is a reference. Inserting it places a pointer to the pattern rather than a copy, the design is rendered from the pattern wherever it is used, and editing the pattern changes every instance at once. The only thing an instance carries of its own is the content of the parts the pattern has marked as editable, its content slots, which is what WordPress calls Pattern Overrides.

WordPress core supports synced patterns for user patterns only. Pattern Builder extends the same behaviour to theme patterns: a theme pattern whose header says Synced: yes is inserted as a reference and rendered from its file, with the same content slots. Because that needs a runtime at render time, a synced theme pattern comes with a production dependency, described in the callout below and in full on Synced theme patterns.

	Unsynced	Synced
Inserting it	Copies the blocks	Places a reference
Editing the pattern	Affects new insertions only	Changes every instance
Editing an instance	Anything	Only the content slots
User pattern	Core	Core
Theme pattern	Core	Pattern Builder, or Synced Patterns for Themes in production

Switching a pattern’s synced status

The Synced status panel flips a pattern between the two. For a theme pattern that writes or removes the Synced: yes header; for a user pattern it sets the post meta core reads. Existing instances are not rewritten: a copy that was inserted while the pattern was unsynced stays a copy.

The header, in full

These are the headers Pattern Builder reads and writes. Title and Slug are required; everything else is present only when it applies.

Header	Meaning
Title	The pattern’s name, as shown in the inserter.
Slug	Its identifier, namespaced with the theme’s slug.
Description	One or two sentences, shown in the inserter and the details sidebar.
Categories	Comma-separated pattern category slugs.
Keywords	Extra search terms for the inserter.
Block Types	The blocks this pattern is offered for; core/post-content makes it a page pattern.
Post Types	With core/post-content, the post types it is offered for.
Template Types	The template types it is offered for in the Site Editor.
Viewport Width	The width, in pixels, the pattern is designed against and previewed at.
Inserter	no hides the pattern from the block inserter.
Synced	yes makes it a synced theme pattern.
Origin	The cloud pattern this one was first copied from, when it is somebody else’s work. Written on install, carried through any number of edits and re-uploads, and never pointing at your own account.
Cloud	Your own copy of this pattern on patternbuilderwp.com, if it has one. This is what the Pattern Source panel reads to offer Update rather than Upload.

The last two are written for you and are worth leaving alone. They live in the pattern file rather than in your database, which is what lets a theme you distribute carry its own attribution and keep its link to the cloud. A user pattern keeps the same two facts in post meta. Duplicating a pattern drops the Cloud link — the duplicate is a new pattern, not a second copy of the same one — and keeps Origin, because the work is still whoever’s it was.