Using DfE Frontend in your services

Use this guide to help you:

  • install DfE Frontend
  • update the prototype to include the DfE Header
Warning DfE Frontend is not a replacement for GOV.UK Frontend.

Install with Node.js package manager (npm)

This guidance is based on a clean install of the GOV.UK Prototype Kit - version 13.

Instructions for setting up a new prototype kit.

If you are installing into a production service or other prototype, you may need to adjust where files are copied to or updated based on your project structure.

Import or apply DfE Frontend after GOV.UK Frontend in your services.

When you have a service you want to integrate DfE Frontend with, in your VS Code or Visual Studio terminal, run:

npm install dfe-frontend-alpha --save

Once installed you'll see dfe-frontend-alpha in your package.json file and node_modules folder.

Get the CSS and Javascript working

Import the styles scss file

Add the following code to the top of your /app/assets/sass/application.scss file:

@import 'node_modules/dfe-frontend-alpha/packages/dfefrontend';

Setting page max width

The DfE Frontend uses a 1200px max width. If you want to use this across your service, add this code to your /app/assets/sass/application.scss file:

.govuk-width-container {max-width: 1200px;}

If you want to use the GOV.UK template, 960px max width, add this code to your /app/assets/sass/application.scss file:

.dfe-width-container {max-width: 960px;}

If your service is being hosted through education.gov.uk domain, you must override the font stack.

Copy the javascript file

Copy /node_modules/dfe-frontend-alpha/dist/dfefrontend.js file to your /app/assets/javascripts folder.

The DfE logo

There might not be an /app/assets/images folder, so create this first.

Copy /node_modules/dfe-frontend-alpha/packages/assets/dfe-logo.png and /node_modules/dfe-frontend-alpha/packages/assets/dfe-logo-alt.png to your /app/assets/images folder.

If your service is hosted on education.gov.uk

You must not use the GOV.UK header or the GDS Transport typeface. Follow the instructions for using the DfE header and DfE font.

Change the GOV.UK header to the DfE Header

Open the /app/views/layouts/main.html file.

Delete the contents of the file and replace with:

{# 1 #} 
{% from 'node_modules/dfe-frontend-alpha/packages/components/header/macro.njk' import header %}

{# 2 #}
{% extends "govuk-prototype-kit/layouts/govuk-branded.njk" %}

{# 3 #}
{% block header %}
  {{ header({
    "showNav": "false",
    "showSearch": "false",
    "showUserName": "false",
    "userName": "",
    "userNameURL": "",
    "selectedNav": pageNav,
    "logoPath": "public/images",
    "homeHref": "/",
    "service": {
      "name": "My service"
    },
    "primaryLinks": [
      {
        "url"  : "",
        "label" : ""
      }
    ]
  })
}}

{% endblock %}

{# 4 #} 
{% block scripts %}
  {{ super() }}
  <script src="/public/javascripts/dfefrontend.js"></script>
{% endblock %}

You can see the full range of variables in the guidance on the header component page.

In this code:

  1. the DfE nunjucks header template is being imported
  2. the standard GOV.UK page layout is being used
  3. the header of the template is being overridden to use the DfE Header
  4. the javascript is being imported globally

Override the font

Add the following code to your application.scss file.

body,
p,
h1,
h2,
h3,
h4,
h5,
h6,
a,
span,
div,
table,
th,
td,
blockquote,
li,
dt,
dd,
tr {
    font-family:
        BlinkMacSystemFont,
        'Segoe UI',
        Roboto,
        Oxygen-Sans,
        Ubuntu,
        Cantarell,
        'Helvetica Neue',
        sans-serif !important;
}

Run your prototype

Run in VS Code terminal:

npm run dev

In the VS Code terminal, you may be asked to send anonymous data to the design system team, select Y or N and press enter to continue.

In your browser, go to: http://localhost:3000 you should see the blue DfE header and content from your /app/views/index.html file.

Contribute to this page on GitHub