Need a consultation?#
Book a short call to get started.
Block patterns and reusable blocks in WordPress
If you repeat a section such as a call to action or a contact box on several pages, you do not have to rebuild it every time. This guide explains block patterns and synced patterns, how they differ and how to register a custom pattern in code.
You placed a "Call us now" section on ten pages and now the phone number has changed. If you built all ten by hand, you must open each one; if you built it once and synced it, a single edit is enough. That difference is exactly what separates block patterns from reusable blocks.
If you are not yet familiar with the editor's basics, read [the WordPress block editor guide](/blog/آموزش-ویرایشگر-بلوک-گوتنبرگ) first.
## Pattern and synced pattern
The block editor has two similar things that behave differently:
| Feature | Regular pattern | Synced pattern |
|---|---|---|
| When inserted | An independent copy is created | It stays linked to the original source |
| Editing one instance | Only that instance changes | All instances change |
| Best for | Layouts where text and images differ each time | Fixed sections such as a contact footer, a notice or a call to action |
A synced pattern is what used to be called a "reusable block". If you see that name in older guides, they mean the same thing. Option names differ a little between WordPress versions; the overall structure has stayed the same.
> Before syncing a section, ask: do I really want all instances to be identical forever? If each page should have its own text, a regular pattern is better.
## Create a pattern from existing blocks
1. In the editor, build a block or group of blocks, and preferably wrap it in a "Group" block so it is easy to select and move.
2. Select the group and, from the block's three-dot menu, choose Create pattern.
3. Give it a clear name, such as "Call to action: free consultation".
4. Pick a category and decide whether it should be synced.
5. To use it, open the block inserter, go to the Patterns tab and choose it.
You can also see the patterns you created in pattern management. The exact path depends on your theme: in block themes it is inside the Site Editor, and in classic themes it is under the Appearance menu or the dashboard. If you work with a block theme, see [block themes and the full Site Editor](/blog/قالب-بلوکی-و-ویرایشگر-سایت).
## Ready-made patterns and categories
WordPress and many themes ship ready-made patterns: headers, footers, pricing lists, testimonials and more. Use them as a starting point, but always adapt the text, colors and spacing to your own brand. A ready-made pattern that ignores the theme's colors and fonts makes the page look inconsistent.
For sites in right-to-left languages such as Arabic or Persian, check text direction, spacing and the pattern's behavior on mobile before publishing; some ready-made patterns are designed for left-to-right languages.
## Register a custom pattern in code
If you have several sites or want patterns to travel with a theme, register them in code. This example works in a simple plugin or in a child theme's `functions.php`. [The WordPress child theme guide](/blog/قالب-فرزند-وردپرس) explains why code should not go into the main theme.
```php
add_action( 'init', function () {
register_block_pattern_category(
'di9-sections',
array( 'label' => __( 'Site sections', 'di9' ) )
);
register_block_pattern(
'di9/cta-box',
array(
'title' => __( 'Call to action', 'di9' ),
'description' => __( 'Heading, short text and a button', 'di9' ),
'categories' => array( 'di9-sections' ),
'content' => '
',
)
);
} );
```
The content is the saved markup of the blocks. The easiest way to produce it is to build the pattern in the editor, open the code editor from the options menu and copy the text. The text values use the `__()` function so they can be translated, and you must replace the button URL with the real URL of your own page.
In modern themes there is an even simpler way: create a PHP file in the theme's `patterns` folder with a descriptive header (title, slug and category) and put the pattern content after it. WordPress registers these files by itself.
## Which one to build when
- A fixed repeating section that must always stay identical: a **synced pattern**.
- A layout where each page gets its own content: a **regular pattern**.
- A pattern that must ship with a theme or plugin and be installed on several sites: a **pattern registered in code**.
- A full page layout: instead of building from scratch, see [building a landing page with Gutenberg](/blog/ساخت-صفحه-فرود-با-گوتنبرگ).
If you delete a synced pattern, you also affect every place that uses it; before deleting, check where it is used and back up the site.
## Maintaining patterns on larger sites
When the number of patterns grows, clear naming becomes important. Name by function ("Contact footer", "Warning box"), not by appearance ("Blue box 2"). Keep categories limited too, so teammates know where to find each pattern.
Update synced patterns carefully: changing one changes all pages at once. Before editing a heavily used pattern, make a copy of it or take a backup. If several people work on the site, give permission to edit synced patterns only to those responsible for design; review WordPress roles with that in mind.
Use patterns for structure only, and do not put time-sensitive text, such as a discount date, inside a synced pattern where it can be forgotten. Finally, check the pattern in the mobile view and in a right-to-left preview if your site needs it.
## Summary
- A regular pattern creates an independent copy each time; a synced pattern is a single source for all instances.
- A synced pattern is the old reusable block and suits fixed sections.
- Build a pattern from existing blocks, give it a clear name and category and insert it from the Patterns tab.
- To ship a pattern with a theme or plugin, register it with `register_block_pattern` or a file in `patterns`.
- Adapt ready-made patterns to your site's colors, fonts and text direction.
Frequently asked questions
How is a block pattern different from a reusable block?
A regular pattern creates an independent copy every time it is inserted, and editing one copy does not affect the others. A reusable block, called a synced pattern in newer versions, is a single source, and editing it changes every place it is used.
How do I turn a block or group of blocks into a pattern?
Select the block or group in the editor, choose Create pattern from the block options menu and give it a name and category. You also choose there whether the pattern is synced. Later you can find it under Patterns in the inserter or in pattern management.
Do block patterns only work with block themes?
No. Patterns work in the post and page editor of any theme. Only some features, such as editing template parts in the Site Editor, need a block theme.
Where should I put a pattern registered in code?
Put it in a child theme or a small plugin, not in the main theme's files, which are lost on update. In modern themes you can also define each pattern as a file in the theme's patterns folder.
Did this article solve your problem?
Thanks! Feedback like this makes our articles better.
Could not be saved. Please try again in a moment.
