Skip to main content

Use Nunjucks

You can use our Nunjucks code to generate the HTML for pages and components.

You can also change the HTML that’s generated by passing options into the Nunjucks code.

If you use Nunjucks, your application will be easier to update when a new version of GOV.UK Frontend is released.

To use Nunjucks, your application and any frameworks that support your application must use Node.js.

You do not need to follow this guidance to use Nunjucks macros in the GOV.UK Prototype Kit.

Before you start

You must first:

Set up Nunjucks and use the page template

  1. Add node_modules/govuk-frontend/dist to your list of Nunjucks paths, so Nunjucks knows where to find the GOV.UK Frontend template and components.

For example:

   nunjucks.configure([
     "node_modules/govuk-frontend/dist",
     "YOUR-VIEWS-FOLDER"
   ]);
  1. Use the GOV.UK Frontend template by adding the following at the top of your view file:
   {% extends "govuk/template.njk" %}
  1. Go to the default page template example on the GOV.UK Design System website, then copy the Nunjucks code into your view file.

You may need to change the paths in the Nunjucks code to get the CSS, assets and JavaScript working.

Find out how to change how the page template works.

Adding a component

Go to any component page on the Design System website, then copy the Nunjucks macro code from the Nunjucks tab of any example.

For example, to add the breadcrumbs component to your page, copy the code from the Nunjucks tab in the first example on the breadcrumbs component page.

Changing a component

You can use options to change how a component looks or behaves.

For example, use the text option to change the text on a button:

{{ govukButton({
  text: "Example button text"
}) }}

To see the options for a component, select the Nunjucks tab of the component example on any Design System website page, then select Nunjucks macro options.

You must sanitise any HTML you pass in to Nunjucks macros you’re using in your live application to protect your website against cross-site scripting (XSS) attacks. You can read more about XSS on the MDN website.