Releases: alphagov/govuk-frontend
GOV.UK Frontend v4.3.1
Recommended changes
Replace deprecated govuk-!-margin-static
and govuk-!-padding-static
classes
We've fixed an error in the naming convention of the static spacing override classes we'd introduced in v4.3.0. These classes should start with govuk-!-static
, and we've now deprecated the incorrect classes.
If you're using the static spacing margin override classes, replace any classes starting with govuk-!-margin-static
with govuk-!-static-margin
. For example: govuk-!-margin-static-2
would become govuk-!-static-margin-2
.
If you're using the static spacing padding override classes, replace any classes starting with govuk-!-padding-static
with govuk-!-static-padding
. For example: govuk-!-padding-static-2
would become govuk-!-static-padding-2
.
We've deprecated the govuk-!-margin-static
and govuk-!-padding-static
classes, and will remove them in a future major release.
This change was introduced in pull request #2770: Fix ordering of properties in static spacing override classes. Thanks to @garrystewart for reporting this issue.
Fixes
We’ve made fixes to GOV.UK Frontend in the following pull requests:
GOV.UK Frontend v4.3.0
New features
Customise the Open Graph image URL without duplicate meta tags
You can now customise the Open Graph image URL included in the head
by setting the opengraphImageUrl
Nunjucks option.
Also, the default Open Graph image URL meta tag will now only be included if you set the either opengraphImageUrl
or assetUrl
.
This was added in pull request #2673: Allow Open Graph image URL to be customised.
Localise the content licence and copyright statements
When using the footer Nunjucks macro, you can now translate the text of the Open Government Licence (OGL) and Crown copyright statements using the contentLicence
and copyright
parameters.
Visit The National Archives' documentation on OGL and Crown copyright for information on what you need to include in these statements.
This was added in pull request #2702: Allow localisation of content licence and copyright notices in Footer.
Pass HTML directly into compatible components
If using the Nunjucks macros, you can now pass HTML content directly into compatible components using the Nunjucks call syntax. If HTML is provided through the call syntax, the nunjucks macro will ignore the HTML and text options.
Components updated to support this syntax are:
- Details
- Error summary (mapped to
descriptionHtml
parameter) - Inset text
- Notification banner
- Panel
This was added in pull request #2734: Update various components to be callable.
Use new override classes to apply static spacing
You can now use static spacing override classes to apply spacing from the static spacing scale to elements of your design.
The new classes start with: govuk-!-static-
followed by either margin-
or padding-
, and then a spacing unit number.
To apply spacing in a single direction, include left-
, right-
, top-
, or bottom-
just before the spacing unit.
For example:
govuk-!-static-margin-9
will apply a 60px margin to all sides of the element at all screen sizesgovuk-!-static-padding-right-5
will apply 25px of padding to the right side of the element at all screen sizesgovuk-!-static-margin-0
will remove all margins at all screen sizes
This was added in pull request #2672: Add static spacing override classes. Thanks to @patrickpatrickpatrick for this contribution.
Deprecated features
Remove deprecated govuk-header__navigation--no-service-name
class in the header
We've deprecated the govuk-header__navigation--no-service-name
class, and will remove it in a future major release.
This was added in pull request #2694: Deprecate .govuk-header__navigation--no-service-name.
Recommended changes
We've recently made some non-breaking changes to GOV.UK Frontend. Implementing these changes will make your service work better.
Add hidden
to the mobile menu button in the header component
If you're not using the Nunjucks macros, add the hidden
attribute to the mobile menu button in the header component. The mobile menu button is govuk-header__menu-button
.
We've changed the header's mobile menu functionality to use the hidden
attribute instead of using CSS to show/hide the mobile menu. Adding hidden
to the mobile menu button by default will make sure that it does not display for users when javascript does not load.
This was added in pull request 2727: Make use of hidden in header navigation functionality. Thanks to @NickColley and @kr8n3r for their contributions.
Fixes
In pull request 2678: Replace ex units with ems for input lengths, we changed how we define input lengths in our CSS. Browsers might now display these inputs as being slightly wider than before. The difference is usually fewer than 3 pixels.
We’ve also made fixes in the following pull requests:
- #2668: Fix Summary List action link alignment
- #2670: Define minimum width for select component - thanks @Nosfistis for reporting this issue
- #2723: Style accordion and tabs text content with govuk-body class
- #2724: Remove redundant aria-hidden attribute from the content when using the Details polyfill
- #2725: Remove padding-right from last column in summary list row - thanks @edwardhorsford for reporting this issue and suggesting a fix
- #2737: Avoid unnecessary spacing-related media queries
- #2747: Ensure accordion uses overriden focus colour - thanks @NickColley for reporting this issue and suggesting a fix
GOV.UK Frontend v4.2.0
New features
Help users navigate through pages with pagination
You can now use pagination to help users navigate forwards and backwards through a series of pages. For example, in search results or guidance that's divided into multiple website pages.
This was added in pull request #2610: Add pagination component.
Check checkboxes by using the values
Nunjucks option
When using the govukCheckboxes
Nunjucks macro, you can now use the values
option to determine which checkboxes should already be checked when the page loads.
For example, values: ['red', 'blue']
would check any checkboxes that have a value
of 'red' or 'blue'.
You can use this option instead of setting the boolean checked
option on each individual checkbox.
This change was introduced in pull request #2616: Allow selecting options by passing current values.
Check a radio button by using the value
Nunjucks option
When using the govukRadios
Nunjucks macro, you can now use the value
option to determine which radio should already be checked when the page loads.
For example, value: 'red'
would check the radio that has a value
of 'red'.
You can use this option instead of setting the boolean checked
option on each individual radio.
This change was introduced in pull request #2616: Allow selecting options by passing current values.
Select an option in a select by using the value
Nunjucks option
When using the govukSelect
Nunjucks macro, you can now use the value
option to determine which option should already be selected when the page loads.
For example, value: 'red'
would select the option that has a value
of 'red'.
You can use this option instead of setting the boolean selected
option on each individual option.
This change was introduced in pull request #2616: Allow selecting options by passing current values.
Recommended changes
Replace deprecated govuk-header__link--service-name
class in the header
If you're not using the Nunjucks macros in the header, replace any instances of the class govuk-header__link--service-name
with govuk-header__service-name
.
We've deprecated the govuk-header__link--service-name
class, and will remove it in a future major release.
This change was introduced in pull request #2617: Do not make the service name in the header a link if no serviceUrl
is provided.
File extensions added for JavaScript ES Module imports
We have updated our component ES module JavaScript to include missing file extensions not provided in release 4.1.0. If you have received an error similar to the following, for example when running or building your application, this fix should resolve the issue.
Cannot find module '../node_modules/govuk-frontend/govuk-esm/common' imported from ../node_modules/govuk-frontend/govuk-esm/all.mjs
You should not need to make any changes if you are successfully importing our JavaScript as ES modules with version 4.1.0, but there still might be config you can remove. For example, removing fullySpecified: false
from your Webpack config file.
This change was introduced in pull request #2658: Add missing mandatory file extensions for ESM JavaScript. Thanks to @colinrotherham and @tvararu for reporting issues and suggesting and testing fixes.
Fixes
We’ve made fixes to GOV.UK Frontend in the following pull requests:
- #2617: Do not make the service name in the header a link if no
serviceUrl
is provided - #2640: Add top padding to accordion section
- #2644: Allow users to use
require.resolve
to import GOV.UK Frontend JavaScript - thanks to @HughePaul for reporting this issue and testing the fix - #2647: Allow users to import sass files via Webpack
sass-loader
- thanks to @Garethp for reporting this issue, and to @Garethp and @richpjames for testing the fix - #2659: Add missing label and legend classes to HTML fixtures
GOV.UK Frontend v4.1.0
New features
Import GOV.UK Frontend JavaScript as ECMAScript (ES) modules
You can now import our component JavaScript into your service as ES modules, if you're using a bundler.
This change allows you to import only the JavaScript you need, and helps reduce duplication of polyfills.
Because we're shipping ES modules in addition to how we currently publish our component JavaScript, this change is backwards compatible. You will not be required to make any changes unless you want to.
If you want to import using ES modules, we recommend you only use import
to import the JavaScript for components you're using in your service. For example:
import { SkipLink, Radios } from 'govuk-frontend'
var $skipLink = document.querySelector('[data-module="govuk-skip-link"]')
if ($skipLink) {
new SkipLink($skipLink).init()
}
var $radios = document.querySelectorAll('[data-module="govuk-radios]')
if ($radios) {
for (var i = 0; i < $radios.length; i++) {
new Radios($radios[i]).init()
}
}
If you need to import all of GOV.UK Frontend's components, then use the initAll
function to initialise them:
import { initAll } from 'govuk-frontend'
initAll()
Depending on the bundler you use, you may also need to make changes to your JavaScript bundler configuration file. You can read more in our installation instructions about importing JavaScript using a bundler.
This was added in pull request #2586: Publish our JavaScript as ES modules alongside Universal Module Definition (UMD).
Recommended changes
We've recently made some non-breaking changes to GOV.UK Frontend. Implementing these changes will make your service work better.
Remove aria-live
from the character count component
If you're not using the Nunjucks macros, remove the aria-live
attribute from the character count message element. This element's content no longer updates, as we've moved the live counter functionality to a new element injected by JavaScript.
This change was introduced in pull request #2577: Refactor character count to inject new element.
Remove pattern
from the date input component
If you're not using the Nunjucks macros, remove pattern="[0-9]*"
from each of the date input's elements.
We originally added the pattern
attribute to make numeric keypad functionality the default functionality in Safari on iOS. However, we no longer need to use it, as the inputmode
attribute provides this functionality for newer Safari versions.
This change was introduced in pull request #2599: Remove pattern
attribute from date input component.
Fixes
We've made the following fixes in pull request #2577: Refactor character count to inject new element:
- fix character count message being repeated twice by screen readers
- fix character count hint text being announced as part of the count message
- fix multiple outdated character count messages being announced at once
- fix character count message being announced when input length is below a defined threshold
We’ve also made fixes in the following pull requests:
- #2549: Fix header with product name focus and hover state length
- #2573: Better handle cases where
$govuk-text-colour
is set to a non-colour value - #2590: Remove
maxlength
attribute fromtextarea
after character count JavaScript has been initialised - #2615: Fix hints for disabled checkboxes or radios appearing darker than the associated labels
GOV.UK Frontend v4.0.1
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 tabindex
attribute from the error summary component
If you're not using Nunjucks macros, remove the tabindex
attribute from the error summary's HTML. The component JavaScript now adds and removes this attribute.
This change was introduced in pull request #2491: Prevent error summary from being refocused after it has been initially focused on page load.
Fixes
We’ve made fixes to GOV.UK Frontend in the following pull requests:
- #2475: Tweak whitespace HTML for text input component to improve readability
- #2494: Allow disabling autofocus on error summary
- #2514: Fix accordion heading style while JavaScript is disabled
- #2515: Add explicit width to summary list row with 'no actions' pseudo-element
- #2524: Fix select component renders with grey background in Firefox and Safari
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 f...
GOV.UK Frontend v3.14.0
New features
Set text alignment with override classes
You can now use the govuk-!-text-align-left
, govuk-!-text-align-centre
and govuk-!-text-align-right
CSS classes to set text alignment on elements.
This was added in pull request #2368: Add text-align
override classes. Thanks to Ed Horsford for reporting this issue.
Define negative spacing using the govuk-spacing
function
You can now pass the negative equivalent of a point from the spacing scale to the govuk-spacing
function to get negative spacing.
For example, govuk-spacing(1)
returns 5px
, and govuk-spacing(-1)
returns -5px
.
This was added in pull request #2367: Allow govuk-spacing
to output negative spacing. Thanks to Chris Hill-Scott for reporting this issue.
Fixes
- #2366: Prevent panel text overflowing when zoomed in on mobile - thanks to Phil Sherry for reporting this issue.
GOV.UK Frontend v3.13.1
3.13.1 (Fix release)
Fixes
We’ve made fixes to GOV.UK Frontend in the following pull requests:
- #2264: Improve focus state for radio and checkbox controls in forced colors mode (for example, Windows High Contrast Mode) – thanks to @adamliptrot-oc for reporting this issue
- #2265: Do not remove focus outline from disabled link buttons in forced colors mode
- #2273: Fix invisible footer on Open Government Licence logo in forced colors mode – thanks to @oscarduignan for reporting this issue
- #2277: Fix invisible start button chevron in forced colors mode
- #2290: Improve support for Internet Explorer 11 with Windows High Contrast Mode
- #2306: Add
max-width
to file upload component - #2312: Remove
padding-right
from details component
GOV.UK Frontend v3.13.0
New features
Add a 'none' option and 'or' divider to checkboxes
You can now add a 'none' option to checkboxes. For example, 'None of the above' or 'None of these options apply to me'.
Use the 'none' option to allow users to state that none of the checkboxes apply to them. Otherwise, users would have to work out that they should leave all the checkboxes unticked.
You can now also add an 'or' divider before the 'none' option. Use the 'or' divider to make the 'none' option more visible to users.
This was added in pull request #2151: Add 'None of the above' and 'or' divider to checkboxes. Thanks to @frankieroberto for contributing this improvement.
Add a nonce
attribute to inline scripts
If your service has a Content Security Policy (CSP), you can now add a nonce
attribute to inline scripts within the Nunjucks page template. To do this, set the cspNonce
Nunjucks variable. However, you should only add this attribute if you're not able to include the hash for the inline scripts in your CSP.
Make sure you understand the security implications of using this attribute, as wrong implementation could affect your service’s security.
Read more about how to configure your CSP to work with GOV.UK Frontend.
This was added in pull request #2245: Allow the CSP nonce
attribute to be set on the inline script in the page template. Thanks to @natcarey for contributing this issue and its solution.
Fixes
We've made the following fixes in pull request #2229: Change approach to fallback PNG in the header to fix blank data URI from triggering Content Security Policy error:
- fix blank data URI from triggering CSP error
- fix alignment of fallback PNG in the header
We’ve also made fixes in the following pull requests:
GOV.UK Frontend v3.12.0
New features
Links are easier to read and have a clearer hover state (opt-in)
Links now have underlines that are consistently thinner and a bit further away from the link text.
Links also have a clearer hover state, where the underline gets thicker to make the link stand out to users.
These changes are an opt-in feature because you may:
- need to make changes to your service to introduce these new link styles consistently
- want to avoid opting in if you have links within a multiple-column layout in your CSS - there is a Chromium bug that affects such links
To enable this feature, set $govuk-new-link-styles
to true
before you import GOV.UK Frontend in your Sass:
// application.scss
$govuk-new-link-styles: true;
@import "govuk-frontend/all";
If you have created your own link styles, you should review them to ensure their use is consistent across your service.
To make it easier to be consistent in your use of link styles, we’ve also introduced new mixins and modifier classes for:
- removing underlines
- displaying white text on dark backgrounds
These new link styles will be enabled by default in a future major version of GOV.UK Frontend.
This was added in pull request #2183: Updates to link styles and link hover states.
Style links to remove underlines
You can now remove underlines from links by using either the:
govuk-link-style-no-underline
mixin in your Sass, orgovuk-link--no-underline
class in your HTML
An underline still appears when the user hovers their cursor over the link.
This was added in pull request #2214: Add no-underline mixin and modifier class.
Style links on dark backgrounds
You can now style links on dark backgrounds to use white text colour by using either the:
govuk-link-style-inverse
mixin in your Sass, orgovuk-link--inverse
class in your HTML
This was added in pull request #2213: Add inverse link mixin and modifier class.
Add links styled as buttons to cookie banners
You can now add links styled as buttons to cookie banners. For example, you can set the Hide button to be a link styled as a button that reloads the page. Use this feature if you set non-essential cookies on the server and want to help users keep their place using progressive enhancement.
This feature is enabled by default.
This was added in pull request #2164: Enable cookie banner to set link styled as a button.
Fixes
- #2132: Improve vertical alignment of phase banner tag on mobile devices – thanks to @matthewmascord for contributing this issue.
- #2157: Use pointer cursor for 'Menu' button in header – thanks to @MalcolmVonMoJ for contributing this issue.
- #2171: Fix padding on GOV.UK logo affecting hover and focus states
- #2186: Fix display of warning text in Edge when Windows High Contrast Mode is enabled
- #2192: Add data-nosnippet to prevent cookie banner text appearing in Google Search snippets
- #2201: Set -webkit-appearance: button on file upload so text is aligned in Safari
- #2205: Stop file upload component 'jumping' on focus
- #2212: Add underline to crown copyright link in footer