Skip to main content

Configure components

You can configure some of the components in GOV.UK Frontend to customise their behaviour or to localise their JavaScript to use a language other than English.

You can configure a component by:

Setting Nunjucks macro options

If you’re using the Nunjucks macros, you can read about configuring a component or find all of the configuration options published on the GOV.UK Design System website.

Passing JavaScript configuration

Read the JavaScript API Reference for the list of options in each component configuration.

The examples below follow our recommended Import JavaScript using a bundler approach and demonstrate how to:

Configure individual component instances

Component constructors accept two arguments:

  1. The HTML element that represents the component.
  2. An optional configuration object.

Although JavaScript configuration objects are optional, configuration can still be provided or overridden by HTML data attributes.

To learn more about how configuration is passed from Nunjucks macros to HTML data attributes, see advanced examples in the localisation options.

Without configuration object

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

import { CharacterCount } from 'govuk-frontend'

const $element = document.querySelector('[data-module="govuk-character-count"]')
new CharacterCount($element)

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

With configuration object

You can pass a configuration object into the constructor’s second argument when creating an instance of a component in JavaScript:

import { CharacterCount } from 'govuk-frontend'

const $element = document.querySelector('[data-module="govuk-character-count"]')

new CharacterCount($element, {
  maxlength: 500,
  i18n: {
    charactersAtLimit: 'No characters left',

    // Object value
    charactersUnderLimit: {
      other: '%{count} characters to go',
      one: '%{count} character to go'
    }
  }
})

Read the JavaScript API Reference for the list of options in each component configuration.

Configure all components using the initAll function

You can pass configuration for components when initialising GOV.UK Frontend using the initAll function.

You can do this by including key-value pairs of camel-cased component names with their configuration options:

import { initAll } from 'govuk-frontend'

initAll({
  characterCount: {
    maxlength: 500,
    i18n: {
      charactersAtLimit: 'No characters left'
    }
  }
})

Initialise only 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:

import { initAll } from 'govuk-frontend'

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

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

Read the JavaScript API Reference for the list of components in the initAll configuration.

JavaScript errors in the browser console

Error messages from components can be logged in the browser console when HTML elements are not found, or to explain why they failed to initialise.

For example, when:

  • GOV.UK Frontend is not supported in the current browser
  • Component templates have missing changes from our release notes
  • Component JavaScript configuration does not match our documentation

If our inline JavaScript snippet from Import JavaScript was not added to the top of the <body class="govuk-template__body"> section you’ll see this error:

SupportError: GOV.UK Frontend initialised without `<body class="govuk-frontend-supported">` from template `<script>` snippet

You should check your application works without errors or some components will not work correctly.

Adding HTML data attributes

If you’re using HTML, you can pass configuration by adding data attributes to the component’s outermost element (the element that has the data-module attribute). This is how our Nunjucks macros forward the configuration to the JavaScript components in the browser. Data attributes use kebab-case.

Some configuration options are grouped under a namespace to keep related options together. For example, the localisation options are grouped under the i18n namespace. When using these options, include the namespace as a prefix followed by a period as part of the attribute name.

For options accepting object values, you’ll need to set one attribute for each key of that object. Suffix the attribute name (including any namespace) with a period and the name of the key in the object.

This example shows the opening tag of a character count component with some configuration options including:

  • a specific number of characters (non-namespaced configuration)
  • a new message for when users reach the specified number of characters (namespaced configuration)
  • two plural forms for when users are under the specified limit of characters (namespaced configuration + object value)
<div
  data-module="govuk-character-count"
  data-maxlength="500"
  data-i18n.characters-at-limit="No characters left"
  data-i18n.characters-under-limit.other="%{count} characters to go"
  data-i18n.characters-under-limit.one="%{count} character to go"
>

If your configuration contains quotes or other reserved HTML characters, you’ll need to escape those characters.

Configuration is read from data attributes when the component is initialised. Changes to the data attributes made after the component has been initialised will have no effect on the behaviour of the component.

You’ll need to convert the JavaScript API Reference configuration options into kebab-case when using data attributes in HTML.