A new approach for a new Pattern Lab

The PHP version of Pattern Lab has been a trusty tool for a long time, especially for many of us working with Twig and component-based theming for Drupal. However, ever since a decision was made to focus development efforts on Pattern Lab Node, it has been clear that it would eventually become necessary to switch from using the PHP version to using the Node version.

Twig developers do not need to worry about compatibility, since thanks to the efforts of Evan Lovely and Salem Ghoweri, Pattern Lab Node now uses a PHP Twig renderer to render Twig templates. This means that templates are rendered using the official PHP implementation of Twig, and it is even possible to add PHP extensions to the Twig environment used by the renderer.

Pattern Lab Node 3.0 is the future of Pattern Lab, with many improvements over the PHP version, especially in the UI. However, it is still in beta and a bit rough around the edges. There have been issues with pseudo-patterns, and more work is needed to support plugins. With well-established development approaches based on the use of data files and plugins in Pattern Lab PHP, how can we make the switch to using the Node version?

A new approach

Limitations can often drive creativity. I do not know if that is the case here, but a great new development approach is being used by folks already using Pattern Lab Node. This approach was described by Evan Lovely in his excellent presentation ‘Pattern Lab: The Definitive How-to’, and is used by Aaron Froehlich and Jeff Amaral in Union, an inspiring project well worth checking out.

The basic idea in this new approach is to use a new type of template in Pattern Lab. These new templates provide demo data for the actual component templates, making traditional Pattern Lab JSON/YAML data files mostly unnecessary.

As an example, if we have a _heading.twig template (note the leading underscore, which hides the pattern in Pattern Lab)

<h1>{{ title }}</h1>

instead of creating a heading.yml data file

title: ‘Hello’

we create a heading-demo.twig template

{% include ‘_heading.twig’ with {‘title’: ‘Hello’} only %}

These demo templates are very similar to ‘presenter’ templates used in component-based Drupal theming, as they only process and pass data to the actual component templates, and do not contain any markup.

Pros and possible cons

Even though plugins like Data Transform Plugin can make plain data files more powerful, using Twig to provide demo data opens up a whole new world of possibilities. For example, demo templates can use Twig extensions that might not be acceptable in plain Twig components. I am certain that there will be a lot of innovation within this approach and related best practices in the future.

One possible drawback is that the Pattern Lab UI will display the Twig source of the demo template instead of the source of the actual component. However, it is only a possible drawback, as in many cases it might actually be useful to show how the component should be included from another template. And it is still possible to use a data file if it is important to show the source of the component itself.

A new version of Shila theme

I have been wanting to switch to using Pattern Lab Node for some time now, and this new approach has made it possible. I have refactored Shila theme, which I use as a starting point for all my Drupal theme projects, to use demo templates. This change makes it possible to use Shila theme with both Pattern Lab PHP and Pattern Lab Node. If you are interested in seeing an example of a full implementation of this new approach, be sure to check out the new version of Shila theme.



Interesting approach. We are using the yml file as a contract between the frontend dev and the backend dev for what data the component can digest.
Having another twig template for demonstration purposes is a neat idea, but defeats this concept.

And the backender has to use „private“ components, which is in my opinion also not ideal.

Thanks for your comment! It is possible to mix the two approaches, so you could still have a ’contract’ data file for the component. It is also possible to show the component’s Twig source in Pattern Lab this way.


Although I like the idea of demo template or having a data.json file for my components, having the data for a component within the same component folder makes that component more reusable and even portable from one project to another.

Completely agree about having component data within the same component folder. Demo templates can be component-specific and that is how I use them in Shila theme, for example. I should have mentioned this in the blog post, so thanks for bringing it up!


To me the the magic is being able to include templates via yml which is essential to mirroring how Drupal renders templates into strings. Avoiding manual includes is key.

So I am not clear how doing that over multiple levels would work with that method.


We're using JSON Schema to power our PatternLab demo data, as well as drupal.org/project/patter…. The JSON schema clearly defines what data is acceptable for the pattern and that means we can use any sample generator we like (including hand-written JSON if we feel like it).


It is possible to emulate Drupal rendering with the demo template approach as well. One could think of it as just writing the YAML files in Twig instead. Also possible to emulate pseudo-patterns using is not defined, which I’ve done in Shila theme. github.com/aleksip/shila-…