Skip to content

GOV.UK Frontend v4.0.0
Compare
Choose a tag to compare
@vanitabarrett vanitabarrett released this 16 Dec 09:15
· 5035 commits to main since this release
v4.0.0
2695c08
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.

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:

Contributors

alex-ju, brucebolt, and 5 other contributors
Assets 3
Loading