[ADR-0019] Use block templates to build block patterns

Use Block Templates for patterns. Gradually start converting existing patterns.

  • Status: accepted

  • Deciders: Development team

Technical Story: Switch on using Wordpress block templates for building block patterns.

Context and Problem Statement

Block patterns are a great way to create and share patterns over various pages and sites: some fiddling in the Visual Editor, a copy/paste and that’s it ! However, a more complex usage of it like using patterns to compose other patterns, creating some variations of those patterns, and maintaining this whole system, has some caveats. Block templates might be better suited for this multifaceted use case.

Our needs:

  • Reusable arrangement of blocks for Editors to insert and edit, shared across all NROs

  • Composable with each others in larger arrangements

  • Possibility to add arguments to make variations in compositions


  • Easy reusability, low maintenance

TLDR; If you have dev capacity, create and maintain block templates. If you only have editors, keep and exchange block patterns.

Decision Drivers

  • Creating patterns requires to generate them in editor, then copy/paste in php code, and adapt various outputs and attributes

  • Composing patterns requires management of arguments, to convert them to json and html attributes

  • Maintaining those patterns would ideally require to regenerate those in the Editor to be on par with last blocks evolutions

Considered Options

  • Making patterns small enough and with enough arguments to reuse in other patterns (the current solution)

  • Generating templates, patterns, from a basic js format at runtime, letting the Editor generate the HTML content (the proposed solution)

  • Generating patterns from a basic js format at build time, letting the Editor libraries generate the HTML content (maybe later ? compatible with proposed solution, less client-intensive, allows to follow and log blocks changes, could self-generate a shareable pattern directory/portal)

Comparison of patterns and templates

Block pattern

Block template


Visual editor + PHP

JS + Json


PHP + Json + HTML

JS, native filtering





static HTML

expanded by Visual Editor, then static HTML


- insert from Patterns tab

- insert from Blocks tab

- insert from Patterns tab if made into a pattern

use in pattern

- in code with PHP

- in editor with insert

- in code with HTML self closing tag

- in editor with insert

use in template

- in editor with insert

- in code with JS

- in editor with insert

editable after insertion



identifiable in block list




This PR demonstrates a Block template system, and a conversion of a pattern to a template. It includes documentation to create new templates.

It is important to keep the source format as simple as possible (a format Gutenberg understands), so it can be included in any other format we create and can be used to generate more complex outputs using native Gutenberg libraries.

Another PR shows how we could convert all patterns to templates.

Decision Outcome

Chosen option: Use Block Templates for patterns. Gradually start converting existing patterns.


Last updated