Skip to content

GOV.UK Frontend v5.0.0
Compare
Choose a tag to compare
@romaricpascal romaricpascal released this 08 Dec 16:17
· 1699 commits to main since this release
v5.0.0
87d7633
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

You can find a summary of the main changes to GOV.UK Frontend v5 on the Frontend site. It's important to note our old frameworks (such as GOV.UK Elements) are no longer compatible with this release. It also stops Internet Explorer 11 from running GOV.UK Frontend JavaScript and removes support completely for Internet Explorer 8 to 10.

Your service will not stop working in Internet Explorer 11, but components will look and behave differently without JavaScript. Read more about how we provide support for different browsers.

Service teams should be using a progressive enhancement approach to make sure users can still access any content and complete their tasks.

If you still need to provide support for older versions of Internet Explorer, you should stay on the latest GOV.UK Frontend v4 release.

If you need it, we have a checklist for the changes you might need to make for v5, which you can view or copy (needs a Google account).

Breaking changes

You must make the following changes when you migrate to this release, or your service might break.

Update package file paths for Sass

In preparation for additional build targets, we've moved our package files into a directory called dist.

Replace govuk-frontend/govuk with govuk-frontend/dist/govuk in any Sass @import paths.

For example:

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

If you've added node_modules/govuk-frontend as a Sass import path, update it with the /dist suffix:

loadPaths: [
  'node_modules/govuk-frontend/dist'
]

If you're building your Sass code through Rails Assets Pipeline or Sprockets, refer to the section 'Update package file paths in Rails Assets Pipeline or Sprockets'.

Refer to the detailed guidance on importing using Sass.

These changes were introduced in #3498: Remove built dist and package from source

Update package file paths for Nunjucks

In preparation for additional build targets, we've moved our package files into a directory called dist.

Replace govuk-frontend with govuk-frontend/dist in any nunjucks.configure() search paths:

nunjucks.configure([
  'node_modules/govuk-frontend/dist'
])

Refer to the detailed guidance on using Nunjucks.

These changes were made in the following pull requests:

Update package file paths for assets such as images and fonts 

In preparation for additional build targets, we've moved our package files into a directory called dist.

If you're serving the assets from the GOV.UK Frontend assets folder (node_modules/govuk-frontend/govuk/assets), update your routing to the new assets path : node_modules/govuk-frontend/dist/govuk/assets.

Refer to the detailed guidance on importing assets.

These changes were introduced in #3498: Remove built dist and package from source

Update package file paths in Rails Assets Pipeline or Sprockets

In preparation for additional build targets, we've moved our package files into a directory called dist.

Update the  node_modules/govuk-frontend part of the path to node_modules/govuk-frontend/dist, if you've added the path to GOV.UK Frontend package inside node_modules to:

These changes were introduced in #3498: Remove built dist and package from source

Update package file paths if including JavaScript directly

In preparation for additional build targets, we've moved our package files into a directory called dist.

If you've set up your routing to serve GOV.UK Frontend's all.js file from node_modules, update the path you're serving to node_modules/govuk-frontend/dist/govuk/govuk-frontend.min.js.

Update any <script> tag with the new path and filename, if necessary. Make sure they have a type="module" attribute. For example:

<script type="module" src="{path-to-javascript}/govuk-frontend.min.js"></script>

Replace <script>window.GOVUKFrontend.initAll()</script> to import and initialise GOV.UK Frontend using ES modules:

<script type="module">
  import { initAll } from '{path-to-javascript}/govuk-frontend.min.js'

  initAll()
</script>

Refer to the detailed guidance on importing JavaScript.

These changes were introduced in #3498: Remove built dist and package from source

Update package file paths for Node.js and other bundlers

In preparation for additional build targets, we've moved our package files into a directory called dist.

If you're importing GOV.UK Frontend using import ... from 'govuk-frontend' or require('govuk-frontend'), you have nothing to change.

If you're using import to import individual components, replace govuk-frontend/govuk with govuk-frontend/dist/govuk. For example:

import Button from 'govuk-frontend/dist/govuk/components/button/button.mjs'

If you're using require to import individual components, replace govuk-frontend/govuk with govuk-frontend/dist/govuk and update the file name to <COMPONENT_NAME>.bundle.js. For example:

const Button  =  require('govuk-frontend/dist/govuk/components/button/button.bundle.js')

Refer to the detailed guidance on importing JavaScript.

These changes were introduced in #3498: Remove built dist and package from source

Verify your code does not rely on polyfills we have now removed

We have removed polyfills for Internet Explorer 8 to 11:

  • DOMTokenList, Element.prototype.classList, Element.prototype.closest, Element.prototype.matches, and Event - required for Internet Explorer 11 and below
  • Element.prototype.dataset - required for Internet Explorer 10 and below
  • Date.now, Document, Element, Element.prototype.nextElementSibling, Element.prototype.previousElementSibling, Function.prototype.bind, Object.defineProperty, String.prototype.trim and Window - required for Internet Explorer 8

However, because these polyfills create or extend global objects ('polluting the global namespace'), you might have other code in your service unintentionally relying on the inclusion of these polyfills. You might need to introduce your own polyfills or rewrite your JavaScript to avoid using the polyfilled features.

These changes were introduced in pull request #3570: Remove Internet Explorer 8 to 10 JavaScript polyfills, helpers, config

Stop Internet Explorer 11 and other older browsers running unsupported JavaScript

Add type="module" to all HTML <script> tags that include or bundle GOV.UK Frontend.

This is to stop Internet Explorer 11 and other older browsers running the JavaScript, which relies on features older browsers might not support and could cause errors.

Please note that <script> with type="module" runs JavaScript in a slightly different way than <script> without `type="module". You'll need to assess the impact of these nuances and make sure that:

  • when your service code is bundled with GOV.UK Frontend it runs as expected in strict mode
  • if you have any code that needs to run after GOV.UK Frontend in its own <script> tag, you'll need to make sure it's using type="module" or defer. This is because the tag loading GOV.UK Frontend will be deferred because of its type="module" attribute
  • code that needs to run without being deferred, is split into its own file and loaded with a <script> tag without type="module"

If your service has JavaScript you want to run successfully in Internet Explorer (for example JavaScript for analytics), you will need to load it in a separate <script> tag without type="module" and make sure its code is compatible with the browsers it should run in (see previous section about polyfills).

These changes were introduced in pull request #3720: Remove IE11 vendor polyfills

Update the <script> snippet at the top of your <body> tag

Page templates now include a new govuk-frontend-supported class on the <body> tag when GOV.UK Frontend JavaScript components are fully supported.

If you are not using our Nunjucks page template, replace the existing snippet:

<script>document.body.className = ((document.body.className) ? document.body.className + ' js-enabled' : 'js-enabled');</script>

with:

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

These changes were introduced in pull request #3801: Add class .govuk-frontend-supported for ES modules support.

Update the hash used by your Content Security Policy

If your Content Security Policy uses a hash to let the snippet above run, you'll need to update it from:

sha256-+6WnXIl4mbFTCARd8N3COQmT3bJJmo32N8q8ZSQAIcU=

to:

sha256-GUQ5ad8JK5KmEWmROf3LZd9ge94daqNvd8xy9YS1iDw=

These changes were introduced in pull request #3801: Add class .govuk-frontend-supported for ES modules support.

Remove calls to component init methods from your JavaScript

If you instantiate individual components, remove any calls to component init methods,  as initialisation now happens automatically. If you initialise the JavaScript using window.GOVUKFrontend.initAll(), you will not need to make any changes.

For example, the following:

new Radios($radio).init()

becomes:

new Radios($radio)

This change was introduced in pull request #4011: Remove component init() methods and initialise in constructor.

Remove Internet Explorer 8 stylesheets, settings and mixins

We no longer support Internet Explorer 8 (IE8) in GOV.UK Frontend or provide dedicated stylesheets for the browser. Remove any references to these stylesheets from your HTML.

We've removed the govuk-if-ie8 and govuk-not-ie8 mixins, and the $govuk-is-ie8 and $govuk-ie8-breakpoint settings. These were deprecated in GOV.UK Frontend v4.6.0.

You should:

  • remove calls to the govuk-if-ie8 mixin entirely (because the code passed to the mixin was only ever for Internet Explorer 8)
  • replace calls to the govuk-not-ie8 mixin with the contents that were previously passed to the mixin (because now we always want the code passed to the mixin)
  • verify your codebase no longer uses these mixins and variables
  • remove ie8 from the $govuk-suppressed-warnings list, if present

If a library you depend on is not yet updated and relies on these mixins and variables, as a temporary workaround you can define the following mixins and variables before importing:

$govuk-is-ie8: false;
$govuk-ie8-breakpoint: ('desktop');
@mixin govuk-if-ie8 {
  @if false {
    @content;
  }
}
@mixin govuk-not-ie8 {@content}

This change was introduced in pull request #3559: Remove IE8-related Sass and CSS build tasks.

Remove references to "Compatibility mode" and related features from your Sass

GOV.UK Frontend is no longer compatible with our old frameworks:

  • GOV.UK Elements
  • GOV.UK Template
  • GOV.UK Frontend Toolkit.

You cannot migrate an existing service to GOV.UK Frontend v5.0 if it is still using one of these frameworks -- you'll need to remain on the latest v4.x release until you've finished the migration. Remove any references to these Sass variables and mixins:

  • $govuk-compatibility-govukelements

  • $govuk-compatibility-govuktemplate

  • $govuk-compatibility-govukfrontendtoolkit

  • the govuk-compatibility mixin which could be used to conditionally output CSS when compatibility mode was enabled

  • remove compatibility-mode from the $govuk-suppressed-warnings list, if present

We've additionally removed features that were managed using the above variables. We've removed the following features and their corresponding variables:

  • access to the legacy colour palette using $govuk-use-legacy-palette
  • access to the legacy font using $govuk-use-legacy-font
  • use of legacy tabular fonts using $govuk-font-family-tabular
  • the ability to not use rem font sizes using $govuk-typography-use-rem

These changes were introduced in:

Remove references to font family variables from your Sass

Remove any references to following Sass variables:

  • $govuk-font-family-gds-transport
  • $govuk-font-family-nta
  • $govuk-font-family-nta-tabular

If you were using $govuk-font-family-gds-transport to set the font on an element, we recommend using the govuk-font mixin instead.

This change was introduced in pull request #3949: Simplify font family settings.

Remove references to govuk-button--disabled class from the HTML for the Button component

For the Button component, remove any references to the govuk-button--disabled class that we deprecated in GOV.UK Frontend v4.6.0.

Use the disabled attribute to mark <button> and <input> elements as being disabled instead.

We no longer support link buttons being disabled or using disabled styles.

This change was introduced in pull request #3557: Remove deprecated govuk-button--disabled class.

Remove references to the JavaScript for the Details component

The Details component no longer uses JavaScript, and is no longer polyfilled in older browsers.

If you are importing the JavaScript for this component individually, remove any references to it.

If you are not using our Nunjucks macros, remove the data-module="govuk-details" attribute from all <details> elements.

We've styled the details component so content does not look 'broken' in browsers that do not support it. If your service supports these browsers,  you will need to add your own polyfills.

This change was introduced in:

Update the GOV.UK logo

We've updated the GOV.UK logo to merge the GOV.UK text with the crown graphic. This is to make sure the full logo is always rendered correctly even if parts of the page, such as CSS or the Transport webfont, fail to load. We've also modified styles relating to the logo.

If you're using the govukHeader Nunjucks macro you don't need to change anything.

Otherwise, to update to the new logo:

  • remove <span class="govuk-header__logotype-text"> and its content
  • remove the <span class="govuk-header__logotype"> around the svg element
  • replace the svg element with this updated SVG, and make sure you also update the class name and attributes

This change was introduced in pull request #4449: Implement transitional crown in the Header component (v5.0).

Check your favicons, app icons and OpenGraph image still work

We've changed the names, formats and sizes of icon assets we distribute in Frontend. You will want to check that the correct files are copied in the right place and served at the right URLs.

The following files have been added to the assets folder:

  • manifest.json
  • images/favicon.svg
  • images/govuk-icon-180.png
  • images/govuk-icon-192.png
  • images/govuk-icon-512.png
  • images/govuk-icon-mask.svg

The following files have been removed from the assets folder:

  • images/govuk-apple-touch-icon.png
  • images/govuk-apple-touch-icon-152x152.png
  • images/govuk-apple-touch-icon-167x167.png
  • images/govuk-apple-touch-icon-180x180.png
  • images/govuk-mask-icon.svg

If you're not using the Nunjucks page template, you will need to replace the list of icons in the template's head with the following:

<link rel="icon" sizes="48x48" href="/assets/images/favicon.ico">
<link rel="icon" sizes="any" href="/assets/images/favicon.svg" type="image/svg+xml">
<link rel="mask-icon" href="/assets/images/govuk-icon-mask.svg" color="#0b0c0c">
<link rel="apple-touch-icon" href="/assets/images/govuk-icon-180.png">
<link rel="manifest" href="/assets/manifest.json">

You will need to update the file path to match your assets folder if it's not at the default location.

This change was introduced in pull request #4445: Implement transitional crown favicons (v5.0).

Remove the fallback GOV.UK crown logo from the  HTML for the Header component

The Header component previously included a fallback PNG version of the GOV.UK crown logo for Internet Explorer 8. As Frontend no longer supports Internet Explorer 8, we've removed this fallback.

If you're not using the Nunjucks macros, you'll need to remove this fallback from your HTML code. In your Header component:

  1. Remove the block of HTML containing the govuk-header__logotype-crown-fallback-image image, starting with <!--[if IE 8]> and ending with <![endif]-->.
  2. Remove <!--[if gt IE 8]><!--> and  <!--<![endif]--> from around the govuk-header__logotype-crown SVG, but don't remove the SVG.
  3. Delete the govuk-logotype-crown.png file from your assets folder.

You do not need to change any HTML if you're using the supplied Nunjucks macros, but you might still need to remove the govuk-logotype-crown.png image depending on how you are serving the font and image assets.

This change was introduced in pull request #3641: Remove fallback GOV.UK logo for IE8.

Remove references to govuk-header__navigation--no-service-name class from the HTML for the Header component

We've removed the govuk-header__navigation--no-service-name class which we deprecated in GOV.UK Frontend v4.3.0.

We no longer supply a dedicated class for headers with navigation but no service name. If you still need this feature, you can reproduce it in your own code using the govuk-spacing Sass mixin.

You could:

  • add a new app-header-navigation class to the header's <nav> tag (you can use the navigationClasses option for the Header component if you're using Nunjucks)
  • add the following styles for this class in your Sass:
.app-header-navigation {
    padding-top: govuk-spacing(7);
}

This change was introduced in pull request #3595: Remove deprecated govuk-header__navigation--no-service-name class.

Add the hidden attribute to the mobile menu button in the Header component

We've removed some styles from the govuk-header__menu-button class. These styles were included on the mobile menu button to avoid introducing a breaking change in GOV.UK Frontend v4.3.0.

If you're not using Nunjucks macros, and have not done so already, add the hidden attribute to the button's HTML to ensure it continues working as expected.

You do not need to make any changes if using the Nunjucks macro.

When working correctly, the button should only show on narrow screens when JavaScript is available. It should be hidden on wider screens or if JavaScript is unavailable.

This change was introduced in pull request #3596: Remove redundant display style from govuk-header__menu-button.

Update references to govuk-header__link--service-name class from the HTML for the Header component

We've removed the govuk-header__link--service-name class which we deprecated in GOV.UK Frontend v4.2.0.

Use the govuk-header__service-name class instead.

This change was introduced in pull request #3594: Remove deprecated govuk-header__link--service-name class.

Update references to govuk-!-margin-static and govuk-!-padding-static classes from the HTML

We've removed the override classes starting with govuk-!-margin-static and govuk-!-padding-static, which were deprecated in GOV.UK Frontend v4.3.1.

Use the classes starting with govuk-!-static-margin and govuk-!-static-padding instead.

This change was introduced in pull request #3593: Remove deprecated static spacing classes.

Update references to the govuk-warning-text__assistive class  from the HTML for the Warning Text component

For the Warning Text component, we've removed the govuk-warning-text__assistive class and its styles from GOV.UK Frontend. This class is unnecessary, as it duplicates the functionality of the govuk-visually-hidden class already present in Frontend.

If you're not using Nunjucks macros, update your warning text HTML to replace the govuk-warning-text__assistive class with the govuk-visually-hidden class.

This change was introduced in pull request #3569: Remove unnecessary class from Warning Text component.

Check your browser console for component initialisation errors

GOV.UK Frontend JavaScript components now provide errors if you initialise a component incorrectly.

These errors will be:

To make sure the components behave as intended, we encourage you to check your browser console and address any errors by updating your markup or configuration.

Errors you might see include:

  • SupportError - when GOV.UK Frontend is not supported in the current browser
  • ElementError - when component templates have missing or broken HTML elements
  • ConfigError - when component JavaScript configuration does not match our documentation

These changes were introduced in:

Check any JavaScript that uses HTMLElement.getAttribute to get the disabled state of a button works as expected

The disabled attribute on 'Disabled buttons' created using our Nunjucks macros no longer includes a value.

If you are using $button.getAttribute('disabled') to check for the disabled attribute in JavaScript, this will now return an empty string. This might cause unexpected behaviour if you are relying on the return value being the string 'disabled' or being truthy.

Instead, we recommend checking for the disabled attribute using $button.hasAttribute('disabled') or the $button.disabled IDL attribute.

This change was introduced in pull request #2830: Set the boolean disabled attribute consistently in the Button component.

Check that inverse buttons still look as expected if you have customised the brand colour

Inverse button components now use the $govuk-brand-colour setting to determine the button's text colour and the button's background tint when hovered or activated. The button will only look different if $govuk-brand-colour has been changed from the default.

You can restore the previous blue colour by setting $govuk-inverse-button-text-colour before importing the button component's Sass.

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

$govuk-inverse-button-text-colour: govuk-colour("blue");

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

This change was introduced in pull request #4043: Add ability to customise inverse button colours.

Check any Selects that have options without explicit values work as expected

The govukSelect macro will no longer include an empty value attribute for options that do not have a value set.

If that option is selected, the value of the Select will become the text content of the option, rather than an empty string.

If you need to maintain the existing behaviour, you can set the value to an empty string.

This change was introduced in pull request #3773: Omit the value attribute from select options with no value.

New features

Use the Task list component to give users an overview of the tasks they need to complete

The Task list component displays all the tasks a user needs to do, and allows users to easily identify which ones are done and which they still need to do.

Each task in the list can have a title, status, link and an optional hint. When a link is added, the whole row is clickable.

This change was introduced in pull request #2261: Task list component..

Use the new focus style for links containing non-text content

We've added a new focus style for use with non-text content, such as links containing images and focusable elements that are not form controls. This new style paints a visible yellow and black outline around the entire element, ensuring the focus style is visible in all situations.

For links containing images, we've added the govuk-link-image class. You should only use this class on links containing an image. If it also contains text, continue to use govuk-link instead.

<a class="govuk-link-image" href="#">
  <img src="..." alt="...">
</a>

You can use these styles in your own code by including the govuk-focused-box Sass mixin.

This change was introduced in pull request #3819: Add linked image focus style.

New link styles are now enabled by default

In GOV.UK Frontend v3.12.0 we introduced new link styles which are now enabled by default. They have:

  • underlines that are consistently thinner and a bit further away from the link text
  • a clearer hover state, where the underline gets thicker to make the link stand out to users

The new link styles are now enabled by default. If you are setting $govuk-new-link-styles to true in your Sass you can now remove this.

This change was introduced in:

Customise the colours of inverse buttons

For non-GOV.UK branded websites, you can now change the colours of inverse buttons - buttons intended for use on dark backgrounds.

To change the inverse button's background colour, set the $govuk-inverse-button-background-colour Sass variable.

To change the inverse button's text colour, set the $govuk-inverse-button-text-colour Sass variable.

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

$govuk-inverse-button-background-colour: govuk-colour("yellow");
$govuk-inverse-button-text-colour: govuk-colour("black");

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

This change was introduced in pull request #4043: Add ability to customise inverse button colours.

Precompiled CSS and JavaScript

The precompiled CSS and JavaScript files found in our GitHub releases are now also published to govuk-frontend on npm.

These changes were introduced in:

Check your tags align with design changes to the Tag component

We've changed the design of the Tag component to improve accessibility and readability.

Text within the tag is no longer bold and uppercase with extra letter spacing. It's now regular 19px text with the first letter of a word capitalised and the rest of the content lowercase. Due to this, there might be changes to the width of existing tags.

The colours have also changed to make them more distinguishable from buttons.

Check your service is using the correct capitalisation in the contents of tags and tags within phase banners.

This change was introduced in:

Recommended changes

We've recently made some non-breaking changes to GOV.UK Frontend. Implementing these changes will make your service work better.

Remove the X-UA-Compatible meta tag

Remove the meta tag from your page template.

Internet Explorer versions 8, 9 and 10 included a feature that would try to determine if the page was built for an older version of IE and would silently enable compatibility mode, which would modify the rendering engine's behaviour to match the older version of IE. Setting this meta tag prevented that behaviour.

Internet Explorer 11 deprecated this meta tag and defaulted to always using IE11's renderer when the page has a HTML5 doctype ().

As Frontend no longer supports Internet Explorer versions older than 11, you can now remove this meta tag.

This change was introduced in pull request #4434: Remove X-UA-Compatible meta tag.

Update the Pagination component's default aria-label

We've updated the default value of the Pagination component's aria-label to be more descriptive of the contents of the region. If you're using the component's default label, you might wish to update it to the new default of 'Pagination'.

You do not need to change anything if you're using the govukPagination Nunjucks macro.

This change was introduced in pull request #3899: Update default aria-label in Pagination component.

Update the Exit this Page button's default text

We've updated the default text of the Exit this Page button. It now includes visually-hidden text to clarify that the button is a safety tool and not a generic method of leaving the current page.

If you are using the component's default text, you might wish to update it to the new value: <span class="govuk-visually-hidden">Emergency</span> Exit this page

You do not need to change anything if you're using the govukExitThisPage Nunjucks macro.

This change was introduced in pull request #3989: Update default Exit This Page button text.

Add the rel attribute to the Exit this Page button and secondary link

Update the Exit this Page button and secondary link to include a new attribute and value: rel="nofollow noreferrer".

Adding this attribute does 2 things:

  • it instructs search engines that your service does not endorse the external website for the purposes of determining search engine rankings
  • it instructs web browsers to not send information about your service to the external website

This fixes a potential risk where the external website could detect that a user had visited from a GOV.UK page and play that information back to the user, which could risk a user's personal safety in some contexts.

You do not need to change the Exit this Page button if you're using the govukExitThisPage Nunjucks macro. You will still have to update the secondary link manually.

This change was introduced in pull request #4054: Add rel attribute to the Exit this Page button. Thanks to Greg Tyler for reporting this issue.

Update titles of the action links inside the Summary Card

If you're not using our Nunjucks macro, we recommend you update the action links :

  • of the Summary Card (inside the element with the govuk-summary-card__actions class)
  • of the Summary List it contains (inside the element with the govuk-summary-list__actions class)

You'll need to either:

  • append a visually hidden <span> with the title of the card, if there's none already
  • or append the title of card to the existing visually hidden span, if there was one already

The final link should be structured as such:

<a class="govuk-link <EXISTING_CLASSES>" <EXISTING_ATTRIBUTES>>
  <EXISTING_VISIBLE_TITLE>
  <span class="govuk-visually-hidden">
    <EXISTING_HIDDEN_TEXT_IF_PRESENT>
    <SUMMARY_CARD_TITLE>
  </span>
</a>

This is to make sure each link has a unique accessible name, which will help users of assistive technology distinguish them from one another.

This change was introduced in pull request #3961: Append card title to action links inside of a Summary Card.

Fixes

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

Thank you

Thanks to everyone who contributed to the GOV.UK Design System 👏👏👏. We’d like to give a big thank you to:

Contributors

simonwhatley, frankieroberto, and 6 other contributors
Assets 3
Loading