Ghost CMS Match Helper Usage & Tips

The match helper allows comparing two values, in a way, it's similar to the {{#has}} helper but it's useful in much more situations and can be used in different contexts.

With {{#match}} comparisons, you can execute different template blocks depending on the result, it supports {{else}} block to execute a different block when the condition is not met.

In addition, it is possible to do {{else match ...}}, to chain together multiple options like a switch statement.

Match helper equality operator

The default behavior is equality:

{{#match @custom.font_family '=' 'Inter'}} ... {{/match}}

This means that if the font_family custom setting is "Inter" the block within the match will be executed. And the above code is the same as:

{{#match @custom.font_family 'Inter'}} ... {{/match}}

If you are checking for equality you don't have to specify the operator ("=") as that is the default one.

You can reverse the check:

{{#match @custom.font_family '!=' 'Inter'}} ... {{/match}}

This means that the block within the match will be executed if the font_family custom setting is NOT "Inter".

Match helper numeric comparisons

The match helper supports operators for numeric comparisons: >, <, >=, <=.

This means that within a {{#get "posts"}} you can use it to check the number of posts and then perform different blocks:

{{#match posts.length '>' 2}}
  {{! Output posts when there are more than 2 }}
{{else}}
  {{! Output posts when there are 2 or less }}
{{/match}}

This way you can output posts in a different way after a certain number.

Similarly, you could check if the number of authors is higher than a specific number (within a {{foreach}}):

{{#match authors.length '>' 1}}
  {{! Output multi authors }}
{{else}}
  {{! Outpost single author }}
{{/match}}

Match helper examples

The match helper is great for many use cases, but especially in combination with Custom settings, so let's explore some use cases and examples:

Font family

We are using the match helper to provide different font family settings in our premium themes. Here are the custom settings from the package.json:

{
  ...
  "config": {
    "custom": {
      "font_family": {
        "type": "select",
        "options": [
          "Inter",
          "Outfit",
          "Inconsolata"
        ],
        "default": "Inter"
       }
       ...
    }
  }
}

Then in the HTML head, the chosen settings are checked and the correct font family is loaded:

{{#match @custom.font_family "Inter"}}
  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800&display=swap" as="style">
  <style>
    body {
      --font-body: 'Inter', sans-serif;
      --font-headings: 'Inter', sans-serif;
    }
  </style>
{{/match}}

In this case, we are using CSS custom properties for the font family, so it's easier to switch to a different font.

Dynamic tag list

Another use case for the match helper is dynamically rendering a list of tags in your Ghost theme. We have the following custom settings setup:

{
  ...
  "tags_slugs": {
    "type": "text",
    "default": "design,ux,ui,web"
  }
}

Then in handlebars, we will use the provided values to fetch a list of tags and then render them in any way we want:

{{#match @custom.tags_slugs '!=' ''}}
  {{#get 'tags' filter='slug:[{{@custom.tags_slugs}}]' limit='all'}}
    {{#if tags}}
      {{#foreach tags}}
        .. render the tag
      {{/foreach}}
    {{/if}}
  {{/get}}
{{/match}}

The first check is to avoid fetching tags when there are no slugs provided, then in the {{get}} helper, we can use the values, which will make the section dynamic with any number of tags, specifically those that you want.

Hero layout

A third example is making a section of the website appear differently, based on the settings chosen from Ghost Admin. In this example, we will look at the hero section layout for the Nikko theme. Here is the custom setting setup:

{
  ...
  "hero_type": {
    "type": "select",
      "options": [
        "cta",
        "featured-slider",
        "none"
      ],
    "default": "none"
   }
}

The admin can select from "cta", "featured-slider" and "none" for the hero type. These options then are implemented in the template files and whichever option is selected is then displayed.

{{#match @custom.hero_type "cta"}}
  {{> hero-subscribe}}
{{/match}}

{{#match @custom.hero_type "featured-slider"}}
  {{> featured-slider}}
{{/match}}

Conclusions

The {{match}} helper is really useful for making Ghost themes more dynamic and especially in combination with custom settings, it provides many more options for theme developers and those who are looking to make their themes more customizable.