Skip to main content
Prototype Kit Training home

Nunjucks

What is Nunjucks?

Nunjucks is the templating framework used by the GOV.UK Prototype Kit. Knowing a few Nunjucks basics will help you work more efficiently.

Nunjucks is installed as part of installing the Prototype Kit - there is nothing to install separately.

You can create Nunjuck files using the .njk extension, but you'll probably find that you only ever need to use Nunjucks within HTML files.

Macros

Macros are essentially shortcuts for generating components and patterns from the GOV.UK Design System. Instead of writing lots of HTML, a simple Nunjucks Macro will generate the exact HTML markup. For example:

Macro syntax used in an HTML file

{{ govukButton({
  text: "Save and continue"
}) }}

Generated HTML

<button class="govuk-button" data-module="govuk-button">
  Save and continue
</button>

Macros have the advantage of being 'update compatible': should a prototype be updated to a new version of the Prototype Kit (or govuk-frontend), any macros used will automatically generate any updated HTML markup, avoiding manual updates. The downside of them is that occasionally you may want control over your exact markup to experiment with slightly different versions of GOV.UK componenents and patterns.

The GOV.UK Design System features all HTML and equivalent macros code snippets, so you can choose which to use. Note that when using the Prototype Kit, you don't need to use the import part of the syntax (eg. {% from "govuk/components/button/macro.njk" import govukButton %}) as the kit imports all relevant macros for you.

There is a useful tool available for Visual Studio Code and Atom that autopopulates Prototype Kit Nunjuck macros for you: GOV.UK Design System Snippets.

Variables

You will be familiar with the notion of a variable if you've covered some of the JavaScript resources. You can 'print out' variables within the HTML in the Prototype Kit using the following Nunjucks syntax.

For example, serviceName is a variable that is defined in every prototype (in app/config.js):

{{ serviceName }}

Variables from session data

{{ data['variable-name'] }}

Session data is information that the Prototype Kit stores in the browser as a user interacts with it. The value of a text input, a checkbox being selected or a radio button being selected for example:

HTML input

<input class="govuk-input" id="citizen-name" name="citizen-name" type="text" value="">

Print the value captured by this input in HTML

{{ data['citizen-name'] }}

Filters

Filters let you 'do stuff' to your variables and other data, using the | symbol (known as 'pipe'). Here are a few examples:

Input

{{ "this is a test" | capitalize }}

HTML Output

This is a test

Input

{{ "TEST" | lower }}

HTML Output

test
{{ data['full-name'] | default("John Smith") }}

Returns John Smith if the full-name session variable is not defined.

All inbuilt Nunjucks filters are listed on the official Nunjucks documentation.

If / else statements

Sometimes known as 'conditional statements', these let you do different things in the prototype depending on the value of something, for example:

{% if data['full-name'] === 'Clark Kent' %}
  <h1>You are Superman</h1>
{% else %}
  <h1>You are not Superman</h1>
{% endif %}

The HTML will say 'You are Superman' in a heading tag if the relevant text input has been completed with the value 'Clark Kent', otherwise it will return 'You are not Superman'.

You can also include an 'elseif' part to the statement:

{% if data['full-name'] === 'Clark Kent' %}
  <h1>You are Superman</h1>
{% elif data['full-name'] === 'Bruce Wayne'  %}
  <h1>You are Batman</h1>
{% else %}
  <h1>You are not a superhero</h1>
{% endif %}

elif is short for elseif - you can use either.

The === is called a comparison, see a full list of comparisons in the Nunjucks documentation.

You can also string different conditions together using and and or

{% if data['full-name'] === 'Clark Kent' or  data['full-name'] === 'Bruce Wayne' %}
  <h1>You are a superhero</h1>
{% else %}
  <h1>You are not a superhero</h1>
{% endif %}
{% if data['full-name'] === 'Clark Kent' and  data['other-name'] === 'Bruce Wayne' %}
  <h1>You are the ultimate superhero</h1>
{% else %}
  <h1>You are not a superhero</h1>
{% endif %}

Templates

extends

Most views (a view just means a page in the Prototype Kit) feature this line of code at the top of the HTML:

{% extends "layout.html" %}

This simply means that the view uses a template called layout.html - which comes with the Prototype Kit. That template can be copied and modified if necessary. The kit also comes with a layout_unbranded.html template.

block

Blocks lets you place content in specific parts of a template. So layout.html provides some blocks, some with default content. This content can then be over written in any view that uses that template.

To override the title of a page, you simply need to populate the pageTitle block in the HTML file of the view you are working in:

{% block pageTitle %}
  Your page title - might be your {{ serviveName }} variable
{% endblock %}

Some other useful blocks available in the Prototype Kit:

{% block beforeContent %}
  Any content that sits below the header but before the main content, such as language toggles and phase banners.
{% endblock %}
{% block content %}
  The main content of your prototype
{% endblock %}

include

This Nunjuck feature lets you include a template within another page. This is particularly useful if you want to include a small section of content on more than one page.

If you were to feature some contact details on different pages in your prototype for example, you would first create a regular HTML file (for example, contact-details.html) with the desired content and save it in your app/views/includes folder. Whenever you want to feature that content in a page, simply include the following:

{% include "includes/contact-details.html" %}

More resources