Patterns for Site Builders

Every pattern in the inserter comes from one of four places, and where it comes from decides whether the site owner can edit it.

Inside user patterns there are two behaviours:

Synced patterns are the old reusable blocks. WordPress 6.3 (August 2023) merged reusable blocks into patterns, added the sync choice when saving a pattern, and let users create unsynced patterns from the editor for the first time. Older books and tutorials still describe "reusable blocks" and a "Manage reusable blocks" link; both are now called patterns, and nothing was lost in the rename: existing reusable blocks became synced patterns with the same IDs. One older handbook aimed at 6.4–6.6 still uses the reusable block terminology throughout; another written for 6.3–6.4 describes patterns correctly but predates pattern overrides (6.6), the content-only editing of unsynced patterns (7.0) and the current location of the Patterns screen.

The workflow is the same in the post editor and the Site Editor:

For a synced pattern the selected blocks are replaced by the new core/block instance at once. For an unsynced pattern the blocks stay as they are and the pattern is just saved for later. Both appear in the inserter: unsynced patterns under Patterns > My patterns and in their categories, synced ones also under the Synced patterns filter. Typing / and the pattern name in an empty paragraph inserts it as well.

A synced pattern placed on 40 pages is referenced by ID from each of those pages. To stop syncing a single use, select it and choose Detach in the toolbar: the instance is replaced by a copy of the blocks, and any override values it carried (next section) are written into the copied blocks.

A plain synced pattern is all or nothing: every instance shows the same text. Pattern overrides, added in WordPress 6.6, let selected blocks inside a synced pattern take different content on each page while the layout and styles stay synced. Lumen Press uses this for a "Book spotlight" pattern: the heading, the blurb and the button change per book, the group, colours and spacing do not.

To enable an override, open the synced pattern with Edit original (or from the Patterns screen), select a supported block, open Advanced in the block settings sidebar and click Enable overrides. A dialog asks for a name, which must be unique inside the pattern because it is the key that links the page’s values to the block. Disable overrides in the same place reverses it. In a page, an overridable block shows its pattern content until an author types over it; the toolbar’s Reset button returns the instance to the pattern’s content.

In WordPress 7.1.3 overrides work on these block attributes, which are the attributes core supports for block bindings:

Before 7.0 the list was hard-coded to core blocks. WordPress 7.0 opened overrides to any block attribute that supports block bindings, so a plugin can make its own block overridable through the block_bindings_supported_attributes filter (a developer topic, covered in Block Bindings API). Containers cannot be overridden: an author cannot add a third button or a second paragraph to one instance.

WordPress 7.0 changed what happens after an unsynced pattern is inserted. The inserted blocks keep a record of the pattern they came from, and the editor treats the whole section as one unit in content-only mode: authors can change text, links and images, but block structure, styles and layout controls are hidden and inner blocks without content are skipped in List View. To restyle or restructure the section, the author clicks Edit pattern in the toolbar or block sidebar (or double-clicks the section), which opens a spotlight mode with full editing. Template parts and synced patterns get the same treatment, except that their button reads Edit original and opens the source in an isolated editor, because a change there affects every use.

Content-only locking already existed since 6.1 as a templateLock value that theme authors could set on a container; the 7.0 change applies it by default to every inserted unsynced pattern. For site owners this is usually welcome (authors stop breaking layouts), but it surprises teams whose Editors are expected to restyle sections freely, and it hides content from custom blocks whose attributes do not declare a content role. A site can turn the default off for unsynced patterns with the disableContentOnlyForUnsyncedPatterns block editor setting. As a must-use plugin:

Source: Make WordPress Core: Pattern Editing in WordPress 7.0

Saved as wp-content/mu-plugins/lumen-pattern-editing.php, it applies to every editor screen. The setting affects only unsynced patterns; synced patterns and template parts remain sections that are edited through Edit original.

User patterns, theme patterns and template parts are managed in one screen of the Site Editor. How it is reached depends on the theme and has changed several times:

The history explains why older screenshots differ: until 6.4 classic themes reached patterns only through the list table at edit.php?post_type=wp_block; 6.5 added Appearance > Patterns pointing at that list table; 6.6 pointed it at the Site Editor’s Patterns screen; 6.8 introduced the Design entry for classic themes with editor styles or theme.json. The old list table URL still works and is handy for bulk trash and for revisions (the wp_block post type supports revisions).

The sidebar of the screen lists All patterns, My patterns, one entry per pattern category, and the template part areas (header, footer, general) of block themes. Each pattern card has an actions menu with Rename, Duplicate, Export as JSON and Delete for user patterns; theme patterns can only be duplicated, which creates an editable user copy. The add button at the top offers Add Pattern, Add Template Part and Import pattern from JSON. Choosing several patterns in the list view and exporting them downloads a ZIP of JSON files.

Deleting a synced pattern does not delete its uses. Pages keep the core/block reference; the editor shows "Block has been deleted or is unavailable" in its place and the front end renders nothing. The same empty output appears when the pattern is a draft, in the trash or password-protected, and a pattern that ends up including itself prints [block rendering halted] when WP_DEBUG and WP_DEBUG_DISPLAY are on.

A user pattern is an ordinary post, so backups, migrations and WP-CLI handle it like any other content:

The table layout itself is on Database Schema. The Lumen Press patterns used on this page were created with WP-CLI, which is also a quick way to seed a staging site:

Source: WP-CLI: wp post create, WP-CLI: wp post term set

Each .html file holds the block markup of one pattern (the spotlight markup is shown in the previous section). Listing them with their sync status:

Source: WP-CLI: wp db query

NULL means the meta row does not exist, that is, the pattern is synced.

The Export as JSON action downloads one file per pattern, named after the pattern title in lowercase with hyphens. The format is small and stable:

Source: WordPress 7.1.3: wp-includes/js/dist/editor.js (export-pattern action)

syncStatus is "unsynced" or an empty string for synced patterns. Import pattern from JSON (in the add menu of the Patterns screen) rejects a file unless __file is wp_block and title and content are non-empty strings, then creates a new published pattern through the REST API; it is synced unless syncStatus is "unsynced". The file does not carry categories: the imported pattern is put in the category selected in the screen’s sidebar at the time (a theme category is turned into a wp_pattern_category term on the fly), or in none when All patterns or My patterns is selected. The file does not carry the pattern ID either: an imported synced pattern gets a new ID on the target site, so pages copied from the source site still reference the old ID and must be re-pointed (or the pages must be migrated together with the patterns by a full export, see Importing, Exporting and Migrating).

For moving many patterns from staging to production, the same format can be produced and consumed with wp eval-file. This exporter writes one file per published user pattern:

Source: WP-CLI: wp eval-file

The importer applies the same checks as the editor and uses wp_slash() because wp_insert_post() expects slashed data; without it, the backslashes in the JSON-encoded block attributes would be stripped and the bindings lost:

Source: Code Reference: wp_insert_post()

Source: WP-CLI: wp eval-file

Importing into the same site creates copies with new IDs and slugs (book-spotlight-2); WordPress does not de-duplicate patterns by title. Arguments to wp eval-file are positional only: an unknown --flag makes WP-CLI stop with "unknown --flag parameter", so categories are assigned afterwards with wp post term set.

User pattern categories are created in the Create pattern dialog, in a pattern’s details panel, or with wp term create wp_pattern_category. There is no separate admin screen for them, so renaming or deleting a category is done with wp term update and wp term delete. Uncategorised user patterns appear only under My patterns and All patterns.

Theme and plugin pattern categories (Banners, Call to action, Text, Gallery and the rest) are registered in code and cannot be renamed in the admin. Lumen Press keeps its own house patterns in one Lumen house user category so that authors find them before the many theme and directory patterns.

wordpress.org/patterns is the public directory of patterns built only from core blocks. A site uses it in three ways:

The remote requests need outbound HTTPS from the server. On hosts that block it, or where only house patterns should be offered, the should_load_remote_block_patterns filter (return false) switches all three remote sources off; theme code can also drop core’s own bundled patterns with remove_theme_support( 'core-block-patterns' ). Both are one-line changes in a must-use plugin or theme, described for developers in Theme Patterns.

User patterns live only in the database, so they are not in Git and do not travel with a theme. A team that wants review and history for its patterns can turn the best ones into theme patterns with Create Block Theme (see Create Block Theme and Version Control).

Block Editor for Authors, Site Editor and Global Styles, Theme Patterns, Block Bindings API, Users, Roles and Profiles, Importing, Exporting and Migrating, Database Schema and WP-CLI.