Every block pattern in WordPress lives in one of two places. It can be a theme pattern — a PHP file in your theme’s patterns/ directory with a small comment header on top — or a user pattern, stored in the database as a wp_block post, the kind you get when you select some blocks and choose “Create pattern.”
Functionally they insert the same way. Strategically they are very different animals, and most pattern headaches come from putting a pattern in the wrong home.
What a theme pattern is good at
A theme pattern is a file, and files have superpowers. They ship with the theme, so every site running the theme gets the pattern automatically. They live in version control, so changes are reviewed and reversible. They survive database resets, staging refreshes, and migrations without a second thought. If you build themes — or build many sites on one parent theme — files are where your canonical patterns belong.
The cost: editing them traditionally means editing PHP by hand, and they are invisible to clients who only see wp-admin.
What a user pattern is good at
A user pattern is a post, and posts have their own superpowers. Anyone with the right capability can create one in the editor, no code involved. They can be synced, so one edit updates every place the pattern is used. They belong to the site rather than the theme, so they survive a redesign.
The cost: they are trapped in one site’s database. Moving them to the next project means exporting JSON by hand, and their images stay behind in the old media library.
A rule of thumb
- Part of the design system? Theme pattern. Heroes, page shells, section layouts that define the site belong in files.
- Owned by the content team? User pattern. Promo banners, announcement bars, anything edited monthly belongs in the database.
- Needs to update everywhere at once? Synced pattern — user by default, or a synced theme pattern if it should ship with the theme.
The good news is that the choice is no longer permanent. Pattern Builder shows both kinds side by side on one screen and converts either into the other — images moved, URLs rewritten — so a pattern can start life as a quick draft in the editor and graduate into the theme when it earns it.