Import CSS, assets and JavaScript

CSS

To import the CSS from GOV.UK Frontend, you can either:

add GOV.UK Frontend’s CSS file to your HTML
import the CSS into your own Sass file

Add the CSS file to your HTML

If you decide to add the CSS to your HTML, you can do one of the following:

set up your routing so requests for the CSS file are served from node_modules/govuk-frontend/dist/govuk/govuk-frontend.min.css
copy the node_modules/govuk-frontend/dist/govuk/govuk-frontend.min.css file into your application

Then link the CSS file inside the <head> tag of your HTML page or page template.

<head>
  <!-- // ... -->
  <link rel="stylesheet" href="<YOUR-STYLESHEETS-FOLDER>/govuk-frontend.min.css">
  <!-- // ... -->
</head>

Import using Sass

To import all the Sass rules from GOV.UK Frontend, add the following to your Sass file:

@import "node_modules/govuk-frontend/dist/govuk/all";

Import specific parts using Sass

If you want to improve how quickly your service’s pages load in browsers, you can import only the Sass rules you need.

Import node_modules/govuk-frontend/dist/govuk/base in your Sass file.
Import the parts of the CSS you need.

For example, add the following to your Sass file to import the CSS you need for a basic GOV.UK page.

@import "node_modules/govuk-frontend/dist/govuk/base";

@import "node_modules/govuk-frontend/dist/govuk/core/all";
@import "node_modules/govuk-frontend/dist/govuk/objects/all";
@import "node_modules/govuk-frontend/dist/govuk/components/footer/index";
@import "node_modules/govuk-frontend/dist/govuk/components/header/index";
@import "node_modules/govuk-frontend/dist/govuk/components/skip-link/index";
@import "node_modules/govuk-frontend/dist/govuk/utilities/all";
@import "node_modules/govuk-frontend/dist/govuk/overrides/all";

You can remove lines that import parts of the CSS you do not need.

You do not need /index at the end of your component imports if you’re using Dart Sass, LibSass 3.6.0 or higher, or Ruby Sass 3.6.0 or higher.

Import an individual component’s CSS using a single Sass import

You can also import a component and all its dependencies without importing node_modules/govuk-frontend/dist/govuk/base first.

To import the button component for example, add the following to your Sass file:

@import "node_modules/govuk-frontend/dist/govuk/components/button/button";

Simplify Sass import paths

If you want to make Sass import paths shorter, add node_modules/govuk-frontend/dist to either your:

Sass load paths
assets paths if you use Ruby in your project

You can then import without using node_modules/govuk-frontend/dist/ in your import path. For example:

@import "govuk/components/button/button";

Override with your own CSS

If you want to override GOV.UK Frontend’s styles with your own styles, @import GOV.UK Frontend’s styles before your own Sass rules.

Silence deprecation warnings from dependencies in Dart Sass

If you’re using Dart Sass 1.33.0 or greater, you may see deprecation warnings when compiling your Sass. For example:

DEPRECATION WARNING: Using / for division is deprecated and will be removed in Dart Sass 2.0.0.

We’re currently unable to fix these deprecation warnings without breaking support for LibSass. However, you can silence the warnings caused by GOV.UK Frontend and other dependencies. Make sure you’re using Dart Sass 1.49.10 or greater, and then if you’re:

calling the Sass compiler from the command line, pass the --quiet-deps flag
using the JavaScript API, include quietDeps: true in the options object

You’ll still see deprecation warnings if you’re using / for division in your own Sass code.

Font and image assets

To use the font and image assets from GOV.UK Frontend, you can either:

serve the assets from the GOV.UK Frontend assets folder - recommended
copy the font and image files into your application

Serve the assets from the GOV.UK Frontend assets folder - recommended

Set up your routing so requests for files in <YOUR-SITE-URL>/assets are served from /node_modules/govuk-frontend/dist/govuk/assets.

For example if you’re using express.js, add the following to your app.js file:

const path = require('path');
app.use('/assets', express.static(path.join(__dirname, '/node_modules/govuk-frontend/dist/govuk/assets')))

Copy the font and image files into your application

If you decide to copy the assets instead, copy the:

/node_modules/govuk-frontend/dist/govuk/assets/images folder to <YOUR-APP>/assets/images
/node_modules/govuk-frontend/dist/govuk/assets/fonts folder to <YOUR-APP>/assets/fonts
/node_modules/govuk-frontend/dist/govuk/assets/manifest.json file to <YOUR-APP>/assets

You should use an automated task or your build pipeline to copy the files, so your project folder stays up to date when we update GOV.UK Frontend.

If you have your own folder structure

If you use a different folder structure than <YOUR-APP>/assets/images and <YOUR-APP>/assets/fonts, you can set Sass variables so that Sass builds the CSS to point to your folders.

Set one of the following before the @import line in your Sass file:

$govuk-assets-path
$govuk-images-path and $govuk-fonts-path

Set the $govuk-assets-path variable if your font and image folders have the same parent folder. For example:

$govuk-assets-path: "/<YOUR-ASSETS-FOLDER>/";

Set the $govuk-images-path and $govuk-fonts-path variables if your font and image folders have different parent folders. For example:

$govuk-images-path: "/<YOUR-IMAGES-FOLDER>/";
$govuk-fonts-path: "/<YOUR-FONTS-FOLDER>/";

You can also use your own function to generate paths, for example if you’re using asset-pipeline in sass-rails. Set the $govuk-image-url-function and $govuk-font-url-function variables to the name of your function.

JavaScript

GOV.UK Frontend JavaScript must be run with <script type="module">.

This protects older browsers, including all versions of Internet Explorer, from running modern JavaScript that it does not support. Read about our browser support for more information.

Before you start

You’ll need to add the following to the top of the <body class="govuk-template__body"> section of your page template if you’re not using our Nunjucks macros.

This snippet adds the .govuk-frontend-supported class in supported browsers:

<script>document.body.className += ' js-enabled' + ('noModule' in HTMLScriptElement.prototype ? ' govuk-frontend-supported' : '');</script>

To import the JavaScript from GOV.UK Frontend, you can either:

add GOV.UK Frontend’s JavaScript file to your HTML
import the JavaScript using a bundler like Webpack

Add the JavaScript file to your HTML

If you decide to add the JavaScript to your HTML, you can do one of the following:

set up your routing so requests for the JavaScript file are served from node_modules/govuk-frontend/dist/govuk/govuk-frontend.min.js
copy the node_modules/govuk-frontend/dist/govuk/govuk-frontend.min.js file into your application

Then import the JavaScript file before the closing </body> tag of your HTML page or page template, and run the initAll function to initialise all the components.

<body class="govuk-template__body">
  <script>document.body.className += ' js-enabled' + ('noModule' in HTMLScriptElement.prototype ? ' govuk-frontend-supported' : '');</script>

  <!-- // ... -->

  <script type="module" src="<YOUR-JAVASCRIPTS-FOLDER>/govuk-frontend.min.js"></script>
  <script type="module">
    import { initAll } from '<YOUR-JAVASCRIPTS-FOLDER>/govuk-frontend.min.js'
    initAll()
  </script>
</body>

Read about how we log JavaScript errors in the browser console to check GOV.UK Frontend has been set up correctly.

Select and initialise an individual component

You can select and initialise a specific component by using its data-module attribute. For example, use govuk-radios to initialise the first radio component on a page:

  <script type="module">
    import { Radios } from '<YOUR-JAVASCRIPTS-FOLDER>/govuk-frontend.min.js'
    const $radio = document.querySelector('[data-module="govuk-radios"]')
    if ($radio) {
      new Radios($radio)
    }
  </script>

When initialised individually, errors are thrown rather than logged. You must check your application works without errors or some components will not work correctly.

Import JavaScript using a bundler

If you decide to import using a bundler, we recommend you use import to only import the JavaScript for components you’re using in your service. For example:

import { SkipLink, Radios } from 'govuk-frontend'

const $skipLink = document.querySelector('[data-module="govuk-skip-link"]')
if ($skipLink) {
  new SkipLink($skipLink)
}

const $radios = document.querySelectorAll('[data-module="govuk-radios]')
$radios.forEach(($radio) => {
  new Radios($radio)
})

If you need to import all of GOV.UK Frontend’s components, then run the initAll function to initialise them:

import { initAll } from 'govuk-frontend'
initAll()

If you’re using a bundler that uses CommonJS like Browserify, you should use require:

const { initAll } = require('govuk-frontend')
initAll()

UMD and `window` globals support

We encourage the use of ECMAScript (ES) modules. For projects that cannot use them and require UMD or window globals, our package contains .bundle.js files.

Select and initialise part of a page

If you update a page with new markup, for example a modal dialogue box, you can run initAll with a scope parameter to initialise the components on part of a page.

For example:

<script type="module">
  import { initAll } from '<YOUR-JAVASCRIPTS-FOLDER>/govuk-frontend.min.js'
  const $modal = document.querySelector('.modal')
  initAll({
    scope: $modal
  })
</script>

If your JavaScript is not working properly

If your site has a Content Security Policy (CSP), the CSP may block the inline JavaScript in the page template. You may see a warning like the following in your browser’s developer tools:

Refused to execute inline script because it violates the following Content Security Policy directive: "default-src 'self'".

To unblock inline JavaScript, do one of the following:

include a hash (recommended)
use a nonce

Make sure you understand the security implications of using either option, as wrong implementation could affect your service’s security. If you’re not sure what to do, talk to a security expert.

Use a hash to unblock inline JavaScript

You can unblock inline JavaScript by including the following hash in your CSP:

sha256-GUQ5ad8JK5KmEWmROf3LZd9ge94daqNvd8xy9YS1iDw=

You do not need to make any changes to the HTML.

Learn more about Content Security Policy on the MDN Web Docs website.

Use a `nonce` attribute to unblock inline JavaScript

If you’re unable to use the hash in your CSP, you can also use a nonce on inline JavaScript.

However, you should provide a nonce that hostile actors cannot guess. Otherwise, they could easily find a way around your CSP.

You should use a value which is:

unique for each HTTP response
generated using a cryptographically-secure random generator
at least 32 characters for hex, or 24 characters for base64

Make sure your script tags do not have any untrusted or unescaped variables.

If you’re using the Nunjucks page template, you can add the nonce attribute by setting the cspNonce variable.