Getting started

Pattern Builder installs like any other plugin and adds one screen, Appearance → Pattern Builder, plus a sidebar in the block editor. This page walks through both.

Install the plugin

From WordPress.org

1. In wp-admin, go to Plugins → Add New and search for Pattern Builder.
2. Click Install Now, then Activate.
3. Open Appearance → Pattern Builder.

You can also download the zip from wordpress.org/plugins/pattern-builder and upload it under Plugins → Add New → Upload Plugin. Pattern Builder needs WordPress 6.8 or later and PHP 7.4 or later.

From GitHub

To run the development version, clone the repository into your plugins directory and build it:

git clone https://github.com/Twenty-Bellows/pattern-builder.git
cd pattern-builder
npm install && composer install
npm run build

The repository also carries a Docker-based WordPress environment (npm run start) if you would rather not install into a site you already have.

Upgrading from 1.x

Pattern Builder 2.0 removed the database mirror that 1.x kept of every theme pattern. On first load after the upgrade a one-time migration rewrites any references to those mirror posts to point at the pattern files, then deletes the mirror posts and the old capabilities. Nothing is needed from you, and the theme’s pattern files are untouched.

The Pattern Builder screen

Appearance → Pattern Builder is a library in the style of the Site Editor’s pattern browser. Across the top are four collections, each with its own search box and category rail:

• User — patterns saved in this site’s database, including any you created in the editor with Create Pattern.
• Theme — patterns that ship as PHP files in the active theme’s patterns directory, and in the parent theme’s if there is one.
• Uploaded — your own cloud library on patternbuilderwp.com, once you have connected an account.
• Directory — the collections Twenty Bellows and partner studios have published, free and premium.

For the two local collections the rail lists the site’s pattern categories; for the two cloud collections it lists cloud collections. The grid itself is a set of square tiles. Every preview, local or cloud, is rendered at one design width of 1400px and scaled into its tile, so a short pattern sits centred and a tall one is cropped at the same point everywhere.

The details sidebar

Selecting a tile fills the sidebar on the right. Two actions sit at the top: Save writes any changes you have staged in the panels below, and Edit opens the pattern in the editor. The panels are the same ones the editor shows:

• Pattern Metadata — Name, Slug, Description, Categories, Keywords and Viewport Width.
• Starter Patterns — Block Types, Post Types, Template Types and Available in Inserter: the headers that decide where WordPress offers the pattern. Theme patterns only, since a database pattern has nowhere to store them.
• Synced status — Synced or Unsynced.
• Pattern Source — where the pattern lives, with Convert to Theme Pattern or Convert to User Pattern, and the cloud upload control when an account is connected.

Changes in these panels are staged on the pattern and written when you click Save, so you can adjust several fields and commit them together.

Creating a pattern

The Create Pattern button opens a dialog that starts from the kind of pattern you want, then asks only for what that kind leaves open. Creating patterns describes each kind.

Editing a pattern

Every pattern, theme or user, is edited in the WordPress post editor. Edit from the Pattern Builder screen opens it there with a Back button that returns you to the screen you came from. Because a pattern is only its blocks, the editor’s title field is hidden; the pattern’s name and description are edited in the Pattern Metadata panel instead. Saving writes a theme pattern back to its PHP file and a user pattern to the database.

The same panels are available from any block editor screen through the Pattern Builder sidebar (the plugin’s icon in the editor’s top-right toolbar). The sidebar’s Browse view lists the site’s patterns; its Configuration view holds the two settings below.

When a synced theme pattern is placed in a page or post, its toolbar carries an Edit Pattern button that opens the pattern itself, so a change reaches every page that uses it.

Images, localization, and reprocessing

Whenever a pattern is saved as a theme file, Pattern Builder imports the images it references into the theme’s assets/images directory and rewrites the markup to point there, so the theme carries its own images rather than depending on one site’s media library. That is the default and needs no setting.

The Configuration view of the editor sidebar holds one action, Reprocess All Theme Patterns, which rewrites every theme pattern file at once, with two options:

• Localize Patterns — wrap the text in each pattern in WordPress’s translation functions, so the strings a theme ships can be translated. Off by default, since it changes the files.
• Import Images to Theme — the same image import a save performs, applied to every pattern. On by default; turn it off to leave image references as they are.

Reprocessing is the way to bring a theme’s existing patterns up to the same standard as ones Pattern Builder wrote: run it once after installing on a theme that was authored by hand.

Usage data

The first time you open the Pattern Builder screen it asks, once per site, whether Pattern Builder may send anonymous usage data. It is genuinely optional and genuinely off until you say yes — there is no pre-ticked box, and declining is a button rather than an absence.

If you allow it, what gets sent is which features were used — a pattern created and what kind, the browser opened, a pattern uploaded or installed, an account connected — along with the versions of the plugin, WordPress and PHP, your locale, your theme’s slug and whether the site is multisite, under a random identifier generated at the moment you opt in. Never the site’s address or name, and never any of your content or your patterns. If you declined and change your mind, the connect panel offers it once more; nothing else asks again.