Using Pseudo-Patterns

Pseudo-patterns give developers and designers the ability to quickly build multiple unique variants of an existing pattern. This feature is especially useful when developing template- and page-style patterns or showing the states of other patterns.

The Pseudo-Pattern File Naming Conventionpermalink

Pseudo-patterns are similar to pattern-specific JSON files but are hinted in such a way that a developer can build a variant of an existing pattern. The basic syntax:

patternName~pseudo-pattern-name.json

The tilde (~) and .json file extension are the hints that Pattern Lab uses to determine that this is a pseudo-pattern. The patternName tells Pattern Lab which existing pattern it should use when rendering the pseudo-pattern. The JSON file itself works exactly like the pattern-specific JSON file. It has the added benefit that the pseudo-pattern will also inherit any values from the existing pattern's pattern-specific JSON file.

The Pseudo-Pattern File Datapermalink

By default, arrays in pseudo-pattern data will be merged with the base pattern's array data on an index basis, effectively creating an array having as many entries as the larger of the two, with the indices declared in the variant replacing the first n of the parent, while keeping the rest. Declaring a larger array in the variant results in only using the variant array. To override this behavior globally you can set the parameter patternMergeVariantArrays in your patternlab-config.json to false. Arrays will then be overwritten and you will only have the variant's array data left.

"patternMergeVariantArrays": false

From a navigation and naming perspective patternName and pseudoPatternName will be combined.

Adding Pseudo-Patterns to Your Projectpermalink

Adding a pseudo-pattern is as simple as naming it correctly and following the pattern-specific JSON file instructions for organizing its content. Let's look at a simple example where we want to show an emergency notification on our homepage Mustache template. Our templates/ directory might look like this:

article.mustache
blog.mustache
homepage.mustache

Our homepage.mustache template might look like this:

<div id="main-container">
	{{# emergency }}
	<div class="emergency">Oh Noes! Emergency!</div>
	{{/ emergency }} { ...a bunch of other content... }
</div>

If our _data.json file doesn't give a value for emergency that section will never show up when homepage.mustache is rendered. Obviously we'd need to show both the regular and emergency states of the homepage but we don't want to duplicate the entire homepage.mustache template. That would be a maintenance nightmare. So let's add our pseudo-pattern:

article.mustache
blog.mustache
homepage.mustache
homepage~emergency.json

In our pseudo-pattern, homepage~emergency.json, we add our emergency attribute:

{
    "emergency": true
}

Now when we generate our site we'll have our homepage template rendered twice. Once as the regular template and once as a pseudo-pattern showing the emergency section. Note that the pseudo-pattern will show up in our navigation as Homepage Emergency.

Using Pseudo-Patterns as Pattern Includespermalink

By default, pseudo-patterns cannot be used as pattern includes. The data included in the pseudo-pattern, the bit that actually controls the magic, cannot be accessed when rendering the pattern include.

Re-ordering Pseudo-Patternspermalink

To learn how to re-order pseudo-patterns, check the documentation for Reorganizing Patterns.

Documenting Pseudo-Patternspermalink

To learn how to document pseudo-patterns, check the documentation for Documenting Patterns to learn more.