Cookies on ons.gov.uk

Cookies are small files stored on your device when you visit a website. We use some essential cookies to make this website work.

We would like to set additional cookies to remember your settings and understand how you use the site. This helps us to improve our services.

View cookies

You have accepted all additional cookies. You have rejected all additional cookies. You can change your cookie preferences at any time.

Skip to main content

Development Templating in Nunjucks

Overview

The ONS Design System uses Nunjucks (opens in a new tab)  as its templating language.

Using Nunjucks in Jinja2 templates

Applications that use Jinja2 (opens in a new tab)  will need to include a small configuration change which will prevent Jinja2 throwing an error when chained parameters are undefined. Further information is available in the Jinja2 documentation (opens in a new tab) .

Add the following import:

from jinja2 import ChainableUndefined

Then add the following configuration change:

jinja_env.undefined = ChainableUndefined

How to set up Nunjucks

npm package

We recommend installing the design system through the npm package (opens in a new tab)  we publish on each release.

In your Nunjucks configuration you’ll need to add node_modules/@ons/design-system/components and node_modules/@ons/design-system/layout to your search paths.

Zip file

You can get all components and templates from a zip file that is created with each design system release (opens in a new tab) . You need to create a script that gets the zip and unpacks the contents. For development, the script could run manually, and the folders added to a .gitignore file. In production, it would need to be run within a build process as part of a continuous integration task.

If you are using Jinja, your script will need to copy the components and layout folders from the unzipped download into your templates folder. This is where Jinja looks for templates as multiple search paths cannot be specified.

The zipped templates have already got the content delivery network (CDN) release version and paths set based on the version of the templates you have downloaded.

How to use Nunjucks with components

Each component contains examples and any context-specific variants. You can copy the Nunjucks code directly from the examples.

Open this example in a new tab (Example Panel With Information)

Example Panel With Information contents

Nunjucks

{% from "components/panel/_macro.njk" import onsPanel %}
{{
    onsPanel({
        "body": '<p>Include all rooms built or converted for use as bedrooms</p>'
    })
}}

Nunjucks macro options

NameTypeRequiredDescription
bodystringtrueThe contents of the panel. This can contain HTML.
titlestringfalseThe title for the error summary panel
headingLevelintfalseNumber used to determine the heading level of the title. Use to ensure the title has a correct semantic order on the page. Defaults to 2
typestringfalseA single value to adjust the component using available variants: “success”, “warn”, “ghost”, “bare”, “error”, “branded”, “warn-branded”, and “announcement”
spaciousbooleanfalseSet to “true” to double the padding spacing surrounding the body content if required
classesstringfalseCustom classes to add to the panel
idstringfalseThe HTML id for the panel
attributesobjectfalseHTML attributes to apply to the panel (for example, data attributes)
assistiveTextPrefixstringfalseSets the visually hidden prefix text for screen readers. Default values for each panel type:
  • information and branded – “Important information: ”
  • success – “Completed: ”
  • warn and warn-branded – “Warning: ”
  • error– “Error: ”
iconTypestringfalseAdds an icon to the panel, before the body content, by setting the icon type
iconSizestringfalseIcon size can be set to match the size of the body content text as detailed in the typography type scale

HTML

<div class="ons-panel ons-panel--info ons-panel--no-title">
  <span class="ons-panel__assistive-text ons-u-vh">Important information: </span>
  <div class="ons-panel__body">
    <p>Include all rooms built or converted for use as bedrooms</p>
  </div>
</div>

Help improve this page

Let us know how we could improve this page, or share your user research findings. Discuss this page on GitHub (opens in a new tab) 

Back to top