Skip to main content
Design System
In Review

HTML Components

A version of the design system implemented as HTML Templates components is currently under development.

These are idiomatic components suitable for applications developed with Nunjucks or Jinja.

Note that the HTML components are currently under design review. Component designs and implementations will change over time, but any breaking changes will be handled with major version increments.

We are also reviewing mechanisms to abstract away the underlying HTML markup when consuming components to simplify updates as components change.

Please check the current status of each HTML component for latest updates.

Install using precompiled files

You can install the Gov IE Frontend global HTML components by copying the CSS, JavaScript, and macro files into your project.

Download the files

  1. Download the govie-frontend.zip asset file from the latest release of @govie-ds/html.
  2. Download the theme.zip asset file from the latest release of @govie-ds/theme-govie.

Integration with Wagtail

Copy CSS and JavaScript

  1. Copy the theme.css file from theme.zip to a folder that can serve static CSS files, e.g. static/css.
  2. Copy the styles.css file from govie-frontend.zip to a folder that can serve static CSS files, e.g. static/css.
  3. Copy the govie-frontend.umd.js file from govie-frontend.zip to a folder that can serve static JavaScript files, e.g. static/js.

Copy Jinja macros

  1. Copy the macros folder from govie-frontend.zip file to a location that can be configured with Jinja.

The macros folder contains both dev and prod versions of Jinja macros. You should configure Wagtail to use the dev macros in non-prod environments, and the prod macros in production.

Configure Jinja templates in Wagtail

  1. Configure Jinja to serve static files within templates, e.g. create a Jinja environment file:
from django.templatetags.static import static
from jinja2 import Environment

def environment(**options):
    env = Environment(**options)
    env.globals.update({
        'static': static,
    })
    return env
  1. Update your Wagtail settings to configure Jinja templates, including the folder for the macros, and a folder for you application templates, and your Jinja environment for serving static files:
TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [
            os.path.join(PROJECT_DIR, "templates"),
        ],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.debug",
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
    {
        'BACKEND': 'django.template.backends.jinja2.Jinja2',
        'APP_DIRS': True,
        "DIRS": [
            os.path.join(PROJECT_DIR, "jinja"),
            os.path.join(PROJECT_DIR, "macros/jinja/dev"),
        ],
        'OPTIONS': {
            'extensions': [
                'wagtail.jinja2tags.core',
                'wagtail.admin.jinja2tags.userbar',
                'wagtail.images.jinja2tags.images',
            ],
            'environment': 'core.jinja2-env.environment',
        },
    }
]

Specify the appropriate folder paths to your application Jinja templates, the Gov IE Frontend global HTML macros, and your Jinja environment file for serving static assets.

  1. Create a Jinja template that uses a Gov IE Frontend global HTML macro in your Jinja templates folder:
{% from 'govie/header/macro.html' import govieHeader %}

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{{ page.title }}</title>
    <link rel="stylesheet" href="{{ static('css/theme.css') }}" />
    <link rel="stylesheet" href="{{ static('css/styles.css') }}" />
  </head>
  <body>
    {{ govieHeader({ 'title': 'Application title' }) }}
    <h1>{{ page.title }}</h1>
    <script src="{{ static('js/govie-frontend.umd.js') }}"></script>
  </body>
</html>

Note that the template needs to include the theme.css, styles.css, and govie-frontend.umd.js files previously copied to a folder that can serve static files.