Development Templating in Nunjucks
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
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/layout to your search paths.
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
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.
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)