GOV.UK Frontend v4.0.0
Breaking changes
This release contains a lot of breaking changes, but we expect many of them will only affect a small number of users. However, to make sure your service still works after you upgrade, you should read the release notes and make any required changes.
Check your accordions still display as expected
We've changed the design of the accordion. You can see its new look and read the revised guidance, particularly about when and when not to use accordions.
You should check your accordions still display as expected if you have any:
- accordions with custom styles
- section headings that contain unusual formatting (for example, wrappers)
You do not need to make changes to the content that accordions hide or show, as this release's changes do not affect it.
These changes were introduced in pull request #2257: Update accordion design. Thanks to @mia-allers-gds, @owenatgov, @nnagewad and @chris-gds for their contributions.
Only use the accordion’s summary line for ‘phrasing content’
The summary line is now inside the HTML button
element, so you can only add 'phrasing content' to it. Do not use any non-phrasing content, as the resulting HTML will not be valid.
This change was introduced in pull request #2257: Update accordion design.
Review and revise the accordion's summary line content
Only add a summary line if you need to, as it's likely to make the button text too long.
If you're already using the summary line, review your use of the summary line to make sure you actually need it.
If you need to keep the summary line, review the accordion guidance and make the summary line as short as possible.
Update the HTML for summary lists
We've updated the HTML for the summary list component to avoid nesting <span>
elements within <dd>
elements, which is invalid HTML. This update only affects you if you have summary lists that include a mix of rows with and without actions. You can read more about adding actions to rows.
If you're not using Nunjucks macros, do not include an empty <span class="govuk-summary-list__actions"></span>
in rows without actions. Instead, add the govuk-summary-list__row--no-actions
modifier class to the row.
This change was introduced in pull request #2323: Avoid invalid nesting of <span>
within a <dd>
in summary list. Thanks to @malcolmhire for reporting this issue.
Update the HTML for navigation in the header
We've updated the HTML for the header. This update only affects you if your header includes navigation.
Any additional classes passed using the navigationClasses
Nunjucks option are now applied to the <nav>
rather than the <ul>
. Check the additional classes are still doing what you expect.
If you're not using Nunjucks macros, then you should:
- move the
<button>
inside the<nav>
, immediately before the<ul>
- move the
aria-label
attribute from the<ul>
to the<nav>
- move the
govuk-header__navigation
class from the<ul>
to the<nav>
- add the
govuk-header__navigation-list
class to the<ul>
Check your changes against the header example in the Design System to make sure you have correctly implemented them.
This change was introduced in pull request #2427: Improve the screen reader experience for the header menu.
Style any custom HTML in your cookie banner
We've removed the default font styles from the cookie banner Sass. This change makes it more obvious when you have not added classes and styles to any custom HTML.
If you're passing custom HTML into the cookie banner component (for example, using the html
Nunjucks parameter), you must make sure you're applying the appropriate classes and styles to that HTML. This could look like, for example, adding the govuk-body
class to any paragraph tags. You must do this to prevent your cookie banner displaying with unstyled text.
This change was introduced in pull request #2432: Remove default font styles from cookie banner Sass.
Update the HTML for hints
In GOV.UK Frontend v3.8.0, we updated the HTML for hints to use a <div>
rather than a <span>
element, to allow the use of block elements. We've now removed the styles which made the hint <span>
display as block.
If you’re not using Nunjucks macros, update your hint HTML to use a <div>
rather than a <span>
. For example: <div id="input-hint" class="govuk-hint"></div>
instead of <span id="input-hint" class="govuk-hint"></span>
.
This change was introduced in pull request #2437: Remove display:block
on hint component.
Include JavaScript for skip link to improve screen reader announcements
We've added JavaScript for the skip link component to set focus to the linked element, for example, the main content on the page. This helps screen readers read the linked content when users use the skip link component.
If you're importing JavaScript for individual components, import the skip link JavaScript.
If you're not using Nunjucks macros, add a data-module="govuk-skip-link"
attribute to the component HTML. For example:
<div class="govuk-skip-link" data-module="govuk-skip-link">
...
</div>
Once you've made the changes, check the skip link JavaScript works. To do this, select the skip link and check the linked element (usually the <main>
element) in the browser has a tabindex
attribute.
This change was introduced in pull request #2450: Set focus to skip link target to improve screen reader announcements.
Update the HTML for error messages
We’ve updated the HTML for the error message component to use a paragraph (<p>
) element instead of a <span>
element, as this is more semantically correct.
If you’re not using Nunjucks macros, swap the <span class="govuk-error-message">
for a <p class="govuk-error-message">
.
This change was introduced in pull request #2452: Update error messages to use paragraph tags instead of spans.
Check components that conditionally reveal content still work
On radios and checkboxes, the JavaScript now looks within the whole page for conditionally-revealed content. Before, it only looked within the same set of radios or checkboxes.
If you see unexpected behaviour, make sure the revealed content's id
is unique within the page the content is on. Reusing the same id
within a page could cause a radio or checkbox to reveal or hide the wrong element, and also means your HTML is invalid.
This change was introduced in pull request #2370: Prevent issues with conditionally revealed content when content id
includes CSS syntax characters.
Check the character count component still works as expected
On character counts, the JavaScript now looks within the whole page for the count message, which will be something similar to “You have 200 characters remaining”. Before, it only looked within the character count component.
If you see unexpected behaviour, make sure the id
for the textarea component is unique within the page the content is on. Reusing the same id
within a page could cause the wrong count message to update, and also means your HTML is invalid.
This change was introduced in pull request #2408: Prevent issues with character count when textarea id
includes CSS syntax characters.
Check individually-imported JavaScript modules work as expected
You do not need to do anything if you have done at least one of the following:
- followed our Getting Started guide and are importing all of the GOV.UK Frontend JavaScript in one go via
all.js
- installed GOV.UK Frontend using precompiled files
We've changed the naming of our components' JavaScript modules so individual imports are now attached to
window.GOVUKFrontend.[ComponentName]
instead of window.GOVUKFrontend
.
You can now import multiple modules without overwriting the previous one, for example:
//= require govuk/components/accordion/accordion.js
//= require govuk/components/button/button.js
# These modules are available under window.GOVUKFrontend.Accordion and window.GOVUKFrontend.Button respectively
If you're importing JavaScript modules individually, you should check any references to window.GOVUKFrontend
in your code and update them to point to the correct component, window.GOVUKFrontend.[ComponentName]
. You can now remove any workarounds you may have implemented.
This change was introduced in pull request #2426: Rename exported JavaScript modules to include component name. Thanks to @alex-ju for reporting this issue.
Import 'base' before importing Sass files from core
or overrides
layers
If you import individual files from the core
or overrides
layers, you might see the error Undefined mixin 'govuk-exports'
or no mixin named govuk-exports
when compiling your Sass.
To fix the error, import node_modules/govuk-frontend/govuk/base
first. For example:
@import "node_modules/govuk-frontend/govuk/base";
@import "node_modules/govuk-frontend/core/typography";
This change was introduced in pull request #2455: Remove 'base' import from files in core
and overrides
layers.
Import 'template' Sass file from the objects
layer instead of the core
layer
If you import the 'template' Sass file from the core
layer, you might see the error File to import not found or unreadable: template
when compiling your Sass.
To fix this error, replace any imports of node_modules/govuk-frontend/govuk/core/template
with node_modules/govuk-frontend/govuk/objects/template
.
This change was introduced in pull request #2463: Move template styles from core
to objects
layer.
Check your footer displays as expected
We’ve made some fixes to the alignment of columns within the footer component, so they now align with our grid. We've also removed the logic that assumes a 2-section layout displays as a 'two-thirds and one-third' layout. Footer sections now display as full-width by default.
If you're using the Nunjucks macros, check your footer displays as expected and use the width
macro option to set the width you want for each section.
If you're not using the Nunjucks macros, check your footer displays as expected and use the standard Design System grid classes on the govuk-footer__section
element to set the width. For example:
<div class="govuk-footer__section govuk-grid-column-two-thirds">...</div>
This change was introduced in pull request #2462: Fix footer alignment with grid classes and add width
macro option.
Remove deprecated $govuk-border-width-form-element-error
variable
In GOV.UK Frontend v3.8.0, we made the border width of form elements in their error state the same as for form elements in their normal state and deprecated the $govuk-border-width-form-element-error
variable.
Before, an element's border got thicker to show the element was in an error state. However, elements in their focused state also have a thicker border. As a result, when users focused an element in an error state, the only visible border-change was from red to black. Not all users could perceive this change. So, we reduced the element border's width, to make sure its thickness changes when users focus.
We've now removed $govuk-border-width-form-element-error
completely.
If you’re referencing $govuk-border-width-form-element-error
in your own Sass, you must remove it. If you're also defining your own error state, you only need to change the border colour.
You should avoid overriding the border width. For example, replace border: $govuk-border-width-form-element-error solid $govuk-error-colour;
with border-color: $govuk-error-colour;
.
You should also remove any override of $govuk-border-width-form-element-error
from your Sass. This override no longer does anything.
This change was introduced in pull request #1963: Remove deprecated $govuk-border-width-form-element-error
variable.
Remove deprecated govuk-main-wrapper
and govuk-main-wrapper--l
mixins
We've removed the govuk-main-wrapper
and govuk-main-wrapper--l
mixins we deprecated in GOV.UK Frontend v3.0.0.
Remove any use of these mixins in your own Sass. You can replace these mixins with direct references to the spacing mixins.
This change was introduced in pull request #2385: Remove deprecated govuk-main-wrapper
and govuk-main-wrapper--l
mixins.
Remove calls to deprecated iff
Sass function
We've removed the iff
function we deprecated in GOV.UK Frontend version 3.6.0.
If you’re calling iff
from your own Sass, you should use Sass's native if
function instead.
This change was introduced in pull request #2409: Remove deprecated iff
Sass function.
Remove deprecated govuk-tag--inactive
class
We've removed the govuk-tag--inactive
class we deprecated in GOV.UK Frontend v3.6.0.
Replace any use of this class with the govuk-tag--grey
class.
This change was introduced in pull request #2417: Remove deprecated govuk-tag--inactive class
.
Recommended changes
We've recently made some other changes to GOV.UK Frontend. While these are not breaking changes, implementing them will make your service work better.
You do not need to do anything if you're using Nunjucks macros.
Change date input from type="number"
to inputmode="numeric"
There are some known issues with inputs of type="number"
. Read our research into the issues with type="number"
.
If you’re not using Nunjucks macros, remove the type="number"
attribute from the date input component.
Replace it with type="text"
and inputmode="numeric"
. For example:
<input class="govuk-input govuk-date-input__input" id="passport-issued-month" name="passport-issued-month" type="text" pattern="[0-9]*" inputmode="numeric">
This change was introduced in pull request #1704: Update date input to use type=text
and inputmode=numeric
.
Fix fallback logo so Chrome will not flag it to screen readers
If you’re not using Nunjucks macros, change the SVG markup within the header, footer and button components. We’ve added this fix so screen readers will not announce the fallback image to users.
For the header, footer and button, replace role="presentation"
with aria-hidden="true"
. For example:
<svg class="govuk-button__start-icon" xmlns="http://www.w3.org/2000/svg" width="17.5" height="19" viewBox="0 0 33 40" aria-hidden="true" focusable="false">
This change was introduced in pull request #1724: Fix fallback logo so Chrome will not flag it to screen readers.
Add data-nosnippet
attribute to cookie banner
Apply a data-nosnippet
attribute to the cookie banner component to stop it appearing in Google Search snippets.
If you’re not using Nunjucks macros, add a new data-nosnippet
attribute to the cookie banner.
<div class="govuk-cookie-banner " data-nosnippet role="region" aria-label="Cookies on your service">
This change was introduced in pull request #2192: Add data-nosnippet
to prevent cookie banner text appearing in Google Search snippets.
Fixes
We’ve made fixes to GOV.UK Frontend in the following pull requests:
- #2255: Prevent conditionally revealed questions getting out of sync when multiple sets of radios and checkboxes contain inputs with the same name
- #2323: Avoid invalid nesting of
<span>
within a<dd>
in summary list - #2370: Prevent issues with conditionally revealed content when content
id
includes CSS syntax characters - #2408: Prevent issues with character count when textarea
id
includes CSS syntax characters - #2426: Rename exported JavaScript modules to include component name
- #2434: Add brand colour for Department for Levelling Up, Housing and Communities (DLUHC) - thanks to @brucebolt for contributing this change
- #2447: Remove bottom margin from navigation on tablets
- #2448: Remove the border from the last item in the collapsible navigation menu in the header