GOV.UK Frontend v5.7.1

To install this version with npm, run npm install govuk-frontend@5.7.1. You can also find more information about how to stay up to date in our documentation.

Recommended changes

Stop setting a value for File upload components

The File upload component currently supports a value parameter, which populates the value HTML attribute of the input.

However, since no modern browser supports passing a value to a file input, we've made the decision to remove this parameter. It has been deprecated and will be removed in a future version of GOV.UK Frontend.

We introduced this change in pull request #5330: Deprecate File upload component's value parameter.

Fixes

We've made fixes to GOV.UK Frontend in the following pull requests:

• #5396: Update various department brand colours

GOV.UK Frontend v5.7.0

To install this version with npm, run npm install govuk-frontend@5.7.0. You can also find more information about how to stay up to date in our documentation.

New features

The Royal Arms has been updated

The Royal Arms in the GOV.UK footer has been updated to reflect the version introduced by King Charles III.

If your service does not use the image directly from the Frontend package, you should ensure the new image is being copied to your service’s image assets folder. By default this folder is located at /assets/images.

If you’re using Nunjucks, the asset path may have been changed by the assetPath global variable or assetsPath parameter on the header component.

Copy the govuk-crest.svg file from /dist/assets/images into your assets folder.

You can safely delete the old image files, named govuk-crest.png and govuk-crest-2x.png.

We introduced this change in pull request #5376: Update the Royal Arms graphic in footer (v5.x).

Components will not longer initialise twice on the same element

GOV.UK Frontend components now throw an error if they've already been initialised on the DOM Element they're receiving for initialisation.
This prevents components from being initialised more than once and therefore not working properly.

We introduced this change in pull request #5272: Prevent multiple initialisations of a single component instance

Respond to initialisation errors when using createAll and initAll

We've added a new onError option for createAll and initAll that lets you respond to initialisation errors.
The functions will continue catching errors and initialising components further down the page if one component fails to initialise,
but this option will let you react to a component failing to initialise. For example, to allow reporting to an error monitoring service.

We introduced this change in:

• pull request #5252: Add onError to createAll
• pull request #5276: Add onError to initAll

Check if GOV.UK Frontend is supported

We've added the isSupported function to let you check if GOV.UK Frontend is supported in the browser running your script.
GOV.UK Frontend components check this automatically, but you may want to use the isSupported function to avoid running some code when GOV.UK Frontend is not supported.

We introduced this change in pull request #5250: Add isSupported to all.mjs

Use our base component to build your own components

We've added a Component class to help you build your own components. It allows you to focus on your components' specific features by handling these shared behaviours across components:

• checking that GOV.UK Frontend is supported
• checking that the component is not already initialised on its root element
• checking the type of the root element and storing it for access within the component as this.$root

We introduced this change in:

• pull request #5350: Export a base Component class.
• pull request #5354: Refactor the root type check in GOVUKFrontendComponent

New brand colour

We've added a brand colour for the Serious Fraud Office in pull request #5389.

Fixes

We've made fixes to GOV.UK Frontend in the following pull requests:

• #5278: Fix service navigation mobile toggle spacing
• #5331: Fix Warning Text font weight when <strong> styles are reset
• #5352: Only apply margin to details summary when open
• #5089: Fix details expanded state not announced on iOS
• #5332: Improve how licence description wraps in the footer

GOV.UK Frontend v4.9.0

To install this version with npm, run npm install govuk-frontend@4.9.0. You can also find more information about how to stay up to date in our documentation.

New features

The Royal Arms has been updated

The Royal Arms in the GOV.UK footer has been updated to reflect the version introduced by King Charles III.

You should ensure that the new image is being copied to your service's image assets folder if it's not being used directly from the Frontend package. By default this folder is located at /assets/images.

If you’re using Nunjucks, the asset path may have been changed by the assetPath global variable or assetsPath parameter on the header component.

Copy the following files from /dist/assets/images into your assets folder. You can safely overwrite the old images.

• govuk-crest.png
• govuk-crest@2x.png

We introduced this change in pull request #5383: Update the Royal Arms graphic in footer (v4.x).

Fixes

We’ve made fixes to GOV.UK Frontend in the following pull requests:

• #5127: Remove direct links to Polyfill[dot]io

GOV.UK Frontend v5.6.0

To install this version with npm, run npm install govuk-frontend@5.6.0. You can also find more information about how to stay up to date in our documentation.

New features

Make it easier to navigate complex services with the Service navigation component

We've added a new Service navigation component to help users to navigate services with multiple top-level sections. This replaces the navigation functions of the Header component, which will be deprecated in a future release of GOV.UK Frontend.

This component includes some features we consider experimental. We intend to iterate these features in response to user feedback. These are:

• moving the service name from the Header to the Service navigation
• providing slots for injecting custom HTML into specified locations within the component

We introduced this change in pull request #5206: Service navigation component.

GOV.UK Frontend v5.5.0

This release includes an updated list of organisations and brand colours. We’ve also added a new feature to stop long words from ‘breaking out’ of components.

To install this version with npm, run npm install govuk-frontend@5.5.0. You can also find more information about how to stay up to date in our documentation.

New features

We've updated the list of organisations and brand colours included in Frontend

We've overhauled the list of organisations and organisation brand colours that are shipped with GOV.UK Frontend.

The previous list was outdated and had not kept up with changes to the machinery of government. We’ve updated the list to:

• add all current government departments and their brand colours
• add variants of brand colours that meet a 4.5:1 contrast ratio against white, where required
• provide warnings if defunct organisations are still being referenced in your Sass code

To enable these changes, set the feature flag variable $govuk-new-organisation-colours to true before you import GOV.UK Frontend in your Sass files:

// application.scss
$govuk-new-organisation-colours: true;
@import "govuk-frontend/all";

You can also silence warnings about defunct organisations by adding organisation-colours to the $govuk-suppressed-warnings setting.

We introduced this change in pull request #3407: Update organisation colours.

Stop long words breaking out of components with govuk-!-text-break-word

We've added a new override class to help display long words with no obvious break points when the space is too narrow to display them on one line. An example of a long word might be an email address entered by a user.

Wrapping the content with the govuk-!-text-break-word class forces words that are too long for the parent element to break onto a new line.

A confirmation email will be sent to <span class="govuk-!-text-break-word">arthur_phillip_dent.42@peoplepersonalitydivision.siriuscyberneticscorporation.corp</span>.

Sass users can also use the govuk-text-break-word mixin.

We introduced this change in pull request #5159: Add break-word typography helper.

Recommended changes

Update the $websafe parameter on the govuk-organisation-colour function

The govuk-organisation-colour Sass function's $websafe parameter has been renamed to $contrast-safe.

This is to more accurately describe the functionality of the parameter.

The old parameter name will stop working in the next major version of GOV.UK Frontend.

We introduced this change in pull request #3407: Update organisation colours.

Fixes

We've made fixes to GOV.UK Frontend in the following pull requests:

• #5046: Skip ‘empty’ tasks in the task list
• #5066: Fix whitespace affecting text alignment in pagination block variant
• #5158: Remove ↑ up and ↓ down arrow key bindings from tabs
• #5191: Fix rendering of Back link's href and text for falsy values

GOV.UK Frontend v5.4.1

To install this version with npm, run npm install govuk-frontend@5.4.1. You can also find more information about how to stay up to date in our documentation.

Recommended changes

Update Breadcrumbs to use nav and aria-label

We've made changes to the Breadcrumbs component to improve how it appears to screen readers.

We've changed the wrapping element to use the nav tag to expose it as a navigational landmark, and added an aria-label attribute to differentiate it as breadcrumb navigation.

This change was introduced in pull request #4995: Update Breadcrumb component to improve screen reader accessibility.

Fixes

We've made fixes to GOV.UK Frontend in the following pull requests:

• #5114: Fix divider width for small checkboxes – thanks to @colinrotherham
• #5043: Refactor the accordion JavaScript
• #5044: Remove session storage checks from accordion JavaScript
• #5060: Reintroduce additional bottom margin to Error Summary content
• #5070: Fix alignment of content in conditional checkboxes and radio buttons
• #5090: Remove redundant tag CSS from phase banner

GOV.UK Frontend v5.4.0

To install this version with npm, run npm install govuk-frontend@5.4.0. You can also find more information about how to stay up to date in our documentation.

This release includes new features to help you include only the components your service uses. Doing this can help reduce the size of the JavaScript and CSS files sent to users, improving their experience.

New features

Create individual components with createAll

We've added a new createAll function that lets you initialise specific components in the same way that initAll does.

The createAll function will:

• find all elements in the page with the corresponding data-module attribute
• instantiate a component object for each element
• catch errors and log them in the console
• return an array of all the successfully instantiated component objects.

import { createAll, Button, Checkboxes } from 'govuk-frontend'

createAll(Button)
createAll(Checkboxes)

You can also pass a config object and a scope within which to search for elements.

You can find out more about how to use the createAll function in our documentation.

This change was introduced in pull request #4975: Add createAll function to initialise individual components.

Use tabular numbers easily with govuk-!-font-tabular-numbers

We've added a new override class for tabular number styling: govuk-!-font-tabular-numbers.

Using tabular numbers can make it easier for users to read numbers intended for comparison to one another, or for numbers that dynamically update.

It was previously only possible to use tabular numbers by using the govuk-font-tabular-numbers Sass mixin.

This change was introduced in pull request #4973: Add override class for tabular numbers.

Deprecated features

Importing layers using all files

You'll see a warning when compiling your Sass if you import any of our layers using the all file. Importing using the all files is deprecated, and we’ll remove them in the next major release.

In your import statements, use a trailing /index rather than /all to load GOV.UK Frontend's files.
For example:

• @import "govuk/index"; instead of @import "govuk/all";;
• @import "govuk/<PATH>/index"; instead of @import "govuk/<PATH>/all";;

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

This change was introduced in pull request #4955: Rename all files to index for our Sass entry points.

Fixes

We've made fixes to GOV.UK Frontend in the following pull requests:

• #4942: Remove duplicate errorMessage argument for the password input component - thanks to Tim South for contributing this change
• #4961: Fix tree-shaking when importing govuk-frontend
• #4963: Fix input value not being set if the value was '0' – thanks to @dwp-dmitri-algazin for reporting this issue
• #4971: Fix Error Summary component outputting list HTML when no errorList is provided
• #442: Update content to streamline installation info
• #438: Split up the 'Import CSS, assets and JavaScript' page

GOV.UK Frontend v5.3.1

To install this version with npm, run npm install govuk-frontend@5.3.1. You can also find more information about how to stay up to date in our documentation.

Fixes

We've made fixes to GOV.UK Frontend in the following pull requests:

• #4906: Update the icon in the warning text component to match the defined text colour and background colour, rather than always being white on black
• #4919: Use canvas colour for cookie banner over hardcoded grey
• #4899: Remove indents from conditional reveals in radios and checkboxes
• #4935: Fix password input button unexpectedly stretching
• #4936: Fix skip link underline being removed when global styles are enabled
• #4938: Fix attributes option ignoring values passed from the safe filter

GOV.UK Frontend v5.3.0

To install this version with npm, run npm install govuk-frontend@5.3.0. You can also find more information about how to stay up to date in our documentation.

New features

Use the Password input component to help users accessibly enter passwords

The Password input component allows users to choose:

• whether their passwords are visible or not
• to enter their passwords in plain text

This helps users use longer and more complex passwords without needing to remember what they've already typed.

This change was introduced in pull request #4442: Create password input component. Thanks to @andysellick for the original contribution.

Recommended changes

Update the HTML for the Character count component

We've updated the HTML for the Character count component. The component wrapper data-module="govuk-character-count" and its form group class="govuk-form-group" are now combined as the same <div>. The hint text used as the count message now appears directly after the <textarea>.

If you're not using Nunjucks macros, then you should:

• move all classes and attributes from the form group <div> to the component wrapper <div>
• remove the opening <div> and closing </div> tags used by the form group
• check the count message is now directly after the <textarea>

The following example shows some HTML and the difference once it’s updated.

HTML before:

<div class="govuk-character-count" data-module="govuk-character-count" data-maxlength="100">
  <div class="govuk-form-group">
    <!-- // Label, hint, error and textarea -->
  </div>
  <!-- // Count message -->
</div>

HTML after:

<div class="govuk-form-group govuk-character-count" data-module="govuk-character-count" data-maxlength="100">
  <!-- // Label, hint, error, textarea and count message -->
</div>

Check your changes against the Character count example in the Design System to make sure you’ve correctly implemented them.

This change was introduced in pull request #4566: Use Character count formGroup as module wrapper.

Remove redundant role attributes from elements

We've made minor changes to the HTML of the page template, as well as the header, footer and pagination components.

You can update your HTML to remove the role attribute from some elements. These include the:

• main role on the main element in the template
• banner role on the header element in the Header component
• contentinfo role on the footer element in the Footer component
• navigation role on the nav element in the Pagination component

These roles were present to support legacy browsers, such as older versions of Internet Explorer. GOV.UK Frontend no longer supports these browsers, so you can now remove these roles.

You do not need to change anything if you're using the Nunjucks versions of the page template or these components,

This change was introduced in pull request #4854: Remove redundant role attributes.

Fixes

We've fixed an upstream issue in the cssnano npm package that caused elements with transparency to render incorrectly in Internet Explorer 11. This affected the pre-compiled CSS files in the GOV.UK Frontend npm package and GitHub releases for versions 5.0, 5.1 and 5.2. This was fixed in:

• #1573: feat: add preset and plugin options for browserslist in the cssnano repository
• #4829: Bump the postcss group with 2 updates

We've made fixes to GOV.UK Frontend in the following pull requests:

• #4811: Use KeyboardEvent.key over deprecated KeyboardEvent.keyCode in the Tabs component
• #4812: Use KeyboardEvent.key over deprecated KeyboardEvent.keyCode in the Button component
• #4813: Remove deprecated KeyboardEvent properties from the Exit this Page component
• #4855: Fix mobile product name being misaligned in new type scale

GOV.UK Frontend v5.2.0

In this release, we’ve adjusted our responsive type scale, which is available behind a feature flag. The type scale change is to make text easier to read on smaller screens. We’ve also deprecated the useTudorCrown parameter.

To install this version with npm, run npm install govuk-frontend@5.2.0. You can also find more information about how to stay up to date in our documentation.

New features

We've adjusted our responsive type scale

We've made the following adjustments to our responsive type scale:

• point 16 now returns 16px across all screen sizes
• point 19 now returns 19px across all screen sizes
• point 24 remains as 24px on large screens
• point 24 now returns 21px on small screens instead of 18px and has a line height 25px instead of 20px
• point 27 remains as 27px on large screens
• point 27 now returns 21px on small screens instead of 18px and has a line height 25px instead of 20px
• point 36 remains as 27px on large screens
• point 36 now returns 27px on small screens instead of 24px and has a line height 30px instead of 25px

To enable these changes, set the feature flag variable $govuk-new-typography-scale to true before you import GOV.UK Frontend in your Sass files:

// application.scss
$govuk-new-typography-scale: true;
@import "govuk-frontend/all";

If your service uses custom elements made using GOV.UK Frontend, test your service against the new typography scale to assess if you need to make any adjustments.

You can read more on upgrading your service to the new type scale in our upgrade guide.

This change was introduced in pull request #2421: Adjust the responsive type scale

Insert custom HTML into component form group wrappers

You can now insert custom HTML into form group wrappers for all components with form fields.

govukInput({
  formGroup: {
    beforeInput: {
      html: "example"
    },
    afterInput: {
      html: "example"
    },
  }
})

This change was introduced in pull request #4567: Add beforeInput(s) and beforeInput(s) options to form groups.

Deprecated features

Stop using the useTudorCrown parameter in the Heading component

The rollout for the revised GOV.UK logo has started and the Tudor crown logo is now shown by default. We’ve deprecated the useTudorCrown parameter and will remove it in the next major release.

You can now remove the useTudorCrown parameter, along with any other adjustments made to display the Tudor crown logo in your service.

This change was introduced in pull request #4740: Make Tudor Crown logo the default

Fixes

We've made fixes to GOV.UK Frontend in the following pull requests:

• #4768: Fix z-index of inputs in Radios and Checkboxes component
• #4784: Fix LibSass calc() compatibility in Radios and Checkboxes