Skip to main content

Import 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>

You should check if our snippet is blocked by a Content Security Policy.

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

  • add the JavaScript file to your HTML
  • import the JavaScript into your own JavaScript file using a bundler

Once imported, you can check if GOV.UK Frontend is supported using the isSupported function.

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.

Import JavaScript using a bundler

If you decide to import using a bundler like Rollup or webpack, the bundled JavaScript files must be added using <script type="module"> in your HTML:

<script type="module" src="<YOUR-JAVASCRIPTS-FOLDER>/app-bundle.min.js"></script>

We encourage the use of ECMAScript (ES) modules, but you should check your bundler does not unnecessarily downgrade modern JavaScript for unsupported browsers.

If your service cannot use ES modules, read about alternative module formats below.

Import individual components

To improve how quickly your service’s pages load in browsers, import only the JavaScript components you need. You can also configure each component when instantiating them.

import { SkipLink, CharacterCount, createAll } from 'govuk-frontend'

createAll(SkipLink)
// You can provide a config for components that use them
createAll(CharacterCount, { maxLength: 500 })

Handling errors during instantiation

The createAll function will log any errors thrown during components instantiation to the console. If you need to catch these errors, you can use its onError option.

import { SkipLink, CharacterCount, createAll } from 'govuk-frontend'

createAll(SkipLink, function(error) {
  // Handle the error here, for example send it to an error monitoring service
})
// You can provide a config for components that use them
createAll(CharacterCount, { maxLength: 500 }, function(error) {
  // Handle the error here, for example send it to an error monitoring service
})

You can also instantiate components manually.

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

const $skipLinks = document.querySelectorAll('[data-module="govuk-skip-link"]')
$skipLinks.forEach(($skipLink) => {
  try {
    new SkipLink($skipLink)
  } catch (error) {
    // Handle the error here, for example send it to an error monitoring service
  }
})

const $characterCounts = document.querySelectorAll('[data-module="govuk-character-count"]')
$characterCounts.forEach(($characterCount) => {

  try {
    // You can provide a config for components that use them
    new CharacterCount($characterCount, {maxLength: 500})
  } catch (error) {
    // Handle the error here, for example send it to an error monitoring service
  }
})

You must check that your application works without errors, or some components will not work correctly.

Import and initialise all components using the initAll function

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()

Initialise only part of a page

If you update a page with new markup, for example a modal dialogue box, you can initialise components on that part of the page only.

Initialise individual components on part of a page

Pass the scope into createAll‘s third argument to initialise individual components:

import { SkipLink, CharacterCount, createAll } from 'govuk-frontend'

const $element = document.querySelector('.app-modal')

// Use `undefined` as second arguments for components 
// that don't need a config
createAll(SkipLink, undefined, $element)
createAll(CharacterCount, { maxLength: 500 }, $element)

Initialise all components on part of a page

Run initAll with a scope parameter to initialise the components on part of a page:

import { initAll } from 'govuk-frontend'

const $element = document.querySelector('.app-modal')

if ($element) {
  initAll({ scope: $element })
}

Import JavaScript using alternative module formats

Universal Module Definition (UMD)

For projects that cannot import ECMAScript (ES) modules, we also publish pre-built Universal Module Definition (UMD) bundles to support the following formats:

  • Asynchronous Module Definition (AMD)
  • Browser window.GOVUKFrontend global
  • CommonJS

Bundlers like Browserify can use require() to import UMD bundles:

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

Rails Assets Pipeline or Sprockets can use require directives to import UMD bundles:

// = require govuk/components/accordion/accordion.bundle.js
const { Accordion } = window.GOVUKFrontend;

Note: Using pre-built bundles instead of ECMAScript (ES) modules will output considerably larger JavaScript files. You can read more about tree shaking on the MDN website.

If our inline JavaScript snippet is blocked by a Content Security Policy

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 console:

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.