Releases: alphagov/govuk-frontend
GOV.UK Frontend v5.0.0
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:
- #3491: Update Review app to import
govuk-frontend
via local package - #3498: Remove built
dist
andpackage
from source
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:
- Rails Assets Pipeline search path using
Rails.application.config.assets.paths
- Sprockets using
append_path
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
, andEvent
- required for Internet Explorer 11 and belowElement.prototype.dataset
- required for Internet Explorer 10 and belowDate.now
,Document
,Element
,Element.prototype.nextElementSibling
,Element.prototype.previousElementSibling
,Function.prototype.bind
,Object.defineProperty
,String.prototype.trim
andWindow
- 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 usingtype="module"
or [defer
](https://developer.mozilla.org/en-US/docs/Web/HTML/Eleme...
GOV.UK Frontend v5.0.0-beta.2
Breaking changes
Update the GOV.UK logo
The GOV.UK logo has been updated to merge the GOV.UK text with the crown graphic. This is to ensure that the full logo is always rendered correctly even if parts of the page, such as CSS or the Transport webfont fail to load. Styles relating to the logo have also been modified.
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 thesvg
element. - Replace the
svg
element with this updated SVG, ensuring that the class name and attributes are also updated.
This change was made 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 that we distribute in Frontend. You will want to check that the correct files are in place.
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 made in pull request #4445: Implement transitional crown favicons (v5.0).
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 http-equiv="X-UA-Compatible" content="IE=edge">
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.
IE11 deprecated this meta tag and defaulted to always using IE11's renderer when the page has a HTML5 doctype (<!DOCTYPE html>
).
As Frontend no longer supports Internet Explorer versions older than 11, this meta tag can now be removed.
This change was made in pull request #4434: Remove X-UA-Compatible meta tag.
Fixes
We’ve made fixes to GOV.UK Frontend in the following pull requests:
GOV.UK Frontend v5.0.0-beta.1
Fixes
We’ve made fixes to GOV.UK Frontend in the following pull requests:
GOV.UK Frontend v5.0.0-beta.0
New features
Added a new Task list component
We’ve added a new component which creates lists of tasks that users need to complete.
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 made in pull request #2261: Task list component..
Added 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 made 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 made in:
- pull request #3599: Enable new link styles by default
- pull request #3600: Remove new link styles feature flag
Customise inverse button colours
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 made 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:
- pull request #3726: Default to ES modules with single Rollup config
- pull request #4241: Add new
govuk-frontend.min.css
package bundle
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 made in:
- pull request #3502: Tag design changes
- pull request #3731: Remove the first letter modifier from the tag component
Breaking changes
You must make the following changes when you migrate to this release, or your service might break.
"Compatibility mode" features are no longer supported
GOV.UK Frontend no longer supports compatibility with our old frameworks:
- GOV.UK Elements
- GOV.UK Template
- GOV.UK Frontend Toolkit.
You can no longer incrementally add GOV.UK Frontend to an existing service using one of these previous frameworks. We have removed the following Sass variables and one mixin which controlled compatibility mode:
$govuk-compatibility-govukelements
$govuk-compatibility-govuktemplate
$govuk-compatibility-govukfrontendtoolkit
- the
compatibility-mode
mixin which automatically checked if any of the 3 control variables were set totrue
We’ve additionally removed features that were managed using the above variables. The following features and their corresponding variables have now been removed:
- 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:
- pull request #3622: Remove compatibility mode variables
- pull request #3602: Remove compatibility-mode mixin
- pull request #3576: Remove legacy colour palette
- pull request #3574: Remove legacy and tabular fonts support
- pull request #3576: Remove $govuk-typography-use-rem setting
Update the HTML for warning text
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.
Update package file paths
In preparation for additional build targets, we've moved our package files into a directory called dist
.
If you’re using Node.js and other bundlers
Replace govuk-frontend/govuk
with govuk-frontend/dist/govuk
in any JavaScript require()
or import
file paths.
For example using require()
:
const Button = require('govuk-frontend/dist/govuk/components/button/button')
For example using import
:
import Button from 'govuk-frontend/dist/govuk/components/button/button.mjs'
If you’re including JavaScript directly
Replace GOV.UK Frontend all.js
with govuk-frontend.min.js
and use <script type="module">
for ES modules:
<script type="module" src="{path-to-javascript}/govuk-frontend.min.js"></script>
Next 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>
If you import JavaScript using a different method, you might need to make some changes.
Refer to the detailed guidance on importing JavaScript.
If you’re using Sass
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 using Nunjucks
Replace govuk-frontend
with govuk-frontend/dist
in any nunjucks.configure()
search paths:
nunjucks.configure([
'node_modules/govuk-frontend/dist'
])
These changes were made in the following pull requests:
- #3491: Update Review app to import
govuk-frontend
via local package - #3498: Remove built
dist
andpackage
from source
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>
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...
GOV.UK Frontend v5.0.0-internal.0
Internal pre-release.
GOV.UK Frontend v4.7.0
New features
Added the Exit This Page component to help users quickly exit a page or service
You can now choose to use the exit this page component to help users quickly leave a page or service which contains sensitive information.
This was added in pull request #2545: Add exit this page component.
Added inverse modifier for buttons on dark backgrounds
You can now choose to use the govuk-button--inverse
class to style buttons on dark backgrounds with a white background colour.
This change was made in pull request #3556: Add inverse button styles.
Added inverse modifier for breadcrumbs on dark backgrounds
You can now choose to use the govuk-breadcrumbs--inverse
class to style breadcrumbs on dark backgrounds with white text, links and arrows.
This change was made in pull request #3774: Add inverse breadcrumb and back link modifiers and styles.
Added inverse modifier for back links on dark backgrounds
You can now choose to use the govuk-back-link--inverse
class to style back links on dark backgrounds with white links and arrows.
This change was made in pull request #3774: Add inverse breadcrumb and back link modifiers and styles.
Fixes
We’ve made fixes to GOV.UK Frontend in the following pull requests:
GOV.UK Frontend v4.6.0
New features
Updated the appearance of disabled form controls
We’ve updated the disabled state of Text Input, Textarea, Select and File Upload components so it is consistent across browsers and devices. They’re also now consistent with the existing disabled styles for Buttons, Checkboxes, and Radios.
Disabled form controls appear at 50% opacity and with an alternative cursor appearance when hovered over.
This was added in pull request #3187: Add disabled styles for form controls.
Added a top-level disabled
parameter to form controls
We’ve updated the Nunjucks macros for Text Input, Textarea, Select and File Upload components to include a top-level disabled
parameter. This will make it easier to enable the disabled state for these controls.
{{ govukInput({
id: "disabled-input",
name: "disabled-input",
value: "Unchangeable value",
disabled: true
}) }}
Disabled form controls have poor contrast and can confuse some users, so avoid them if possible.
Only use disabled form controls if research shows it makes the user interface easier to understand.
This was added in pull request #3187: Add disabled styles for form controls.
Configure whether the Accordion remembers and restores sessions
By default, when a user leaves a page, the Accordion will remember the layout of expanded and collapsed sections selected by the user. If the user returns to the page, this layout will be restored and override any sections manually set as expanded in code.
You can now disable this functionality by using the rememberExpanded
option in the govukAccordion
Nunjucks macro.
If you're not using the Nunjucks macro, you can disable it using the data-remember-expanded
HTML attribute.
This was added in pull request #3342: Add option to disable sessionState in Accordion.
Added id
parameter to Buttons
We’ve updated the Button Nunjucks macro to include an optional id
parameter.
{{ govukButton({
text: "Save and continue",
id: "continue-button"
}) }}
This was added in pull request #3344: Adding optional ‘id’ attribute to button component.
Thanks to @TomBillingtonUK for this contribution.
Added a modifier for text input styles that accept sequences of digits
We've added a new .govuk-input--extra-letter-spacing
class for Text Input. This increases readability of text inputs that receive sequences of digits (like security codes, references or phone numbers).
You can add it through the classes
option when using Nunjucks, or directly in the class
attribute of the <input>
when using HTML.
This was added in pull request #2230: Add extra letter spacing modifier for inputs
Deprecated features
Stop using JavaScript API properties other than the init
method
We have deprecated all of the JavaScript properties in the API, except for the init
method for each component. We'll make all of the deprecated JavaScript properties private in our next main release.
Please let us know if you're using parts of the API other than the init
method by filling in this form. We'll use this information when prioritising future additions to the public API.
This was added in pull request #3499: Deprecate all JavaScript instance properties the except init
method.
Stop using the .govuk-button--disabled
class on buttons
We have deprecated the .govuk-button--disabled
class and will remove it in the next major release.
If a Button uses a <button>
or <input>
element, use the disabled HTML attribute instead.
You will not need to make any changes if you're using the govukButton
Nunjucks macro.
Disabling links that are styled to look like buttons will not be supported by future releases.
This was added in pull request #3326: Deprecate govuk-button--disabled
class.
Stop using the deprecated Internet Explorer 8 mixins and settings
The next main release of GOV.UK Frontend will remove support for Internet Explorer 8 (IE8). In preparation for this, we've deprecated the settings and mixins used when generating IE8 specific stylesheets.
You'll start seeing deprecation warnings if you're:
- using the
govuk-if-ie8
andgovuk-not-ie8
mixins in your own Sass code (for example@include govuk-if-ie8
) - changing the
$govuk-is-ie8
and$govuk-ie8-breakpoint
settings to anything other than their default values
If you no longer need to support IE8, we recommend you stop generating an IE8 specific stylesheet and remove references to the IE8 mixins from your code.
You can also silence these deprecation warnings by adding ie8
to the $govuk-suppressed-warnings
setting, but once we’ve released v5.0 you will need to address them as part of the upgrade process.
Fixes
We’ve made fixes to GOV.UK Frontend in the following pull requests:
- #3255: Including the JavaScript source map in the prototype kit config
- #3272: Add empty alt attribute to logo IE8 fallback PNG
- #3306: Re-enable complete hover link styles on the footer
- #3312: Add default value for warning text icon fallback attribute
- #3426: Add organisation brand colour for Department for Business & Trade - thanks to @baisa for contributing this change
- #3454: Update default link underline offset setting
GOV.UK Frontend v4.5.0
New features
Use summary cards to visually separate multiple summary lists on a single page
You can now use the summary card. This new variant of the Summary list component can help you:
- design and build pages with multiple summary lists
- show visual dividers between summary lists
- allow users to apply actions to entire lists
This was added in pull request #2931: Add summary card enhancement to summary list.
Search within accordion content on supporting browsers
We've updated the Accordion component to use the new hidden="until-found"
attribute value.
This allows the browser's native 'find in page' functionality to search within and automatically open sections of the accordion. Currently, this functionality is only supported by recent versions of Google Chrome, Microsoft Edge and Samsung Internet.
This was added in pull requests:
- #3053: Enhance the Accordion component with
hidden='until-found'
- #3095: Hide Accordion content (again) during
.js-enabled
page load
Source maps for precompiled files
You can now use source maps to help identify errors and console messages from GOV.UK Frontend precompiled files.
This was added in pull request #3023: Add source maps to compiled JavaScript and CSS.
Fixes
We've fixed errors in IE8 caused by updates to our precompiled JavaScript. The issue prevented some polyfills from running, but was limited to the release-v4.4.1.zip
and release-v4.4.0.zip
assets on GitHub releases:
- #3137: Enable UglifyJS compatibility workarounds
- #3013: Swap JavaScript minifier from UglifyJS to terser
We've made fixes to GOV.UK Frontend in the following pull requests:
- #2998: Refactor back link and breadcrumb chevrons to use ems
- #3021: Change colour for current page link in the header to improve contrast when printing - thanks to @MalcolmVonMoJ for the contribution
- #3094: Fix Accordion margin/padding inconsistencies
- #3112: Remove unused
classList
polyfill from header component JavaScript - #3150: Add missing
Event
polyfill to accordion component JavaScript - #3156: Correct the closing double quotes in pagination Nunjucks - thanks to @JoPintoPaul for the contribution
- #3199: Fix Sass rounding issues with width of grid columns
GOV.UK Frontend v4.4.1
Fixes
We've made fixes to GOV.UK Frontend in the following pull requests:
GOV.UK Frontend v4.4.0
New features
Change the Button component's background and text colour
For non-GOV.UK branded websites, you can now change the Button component background and text colour.
To change the Button component background colour, set the $govuk-button-background-colour
Sass variable.
To change the Button component text colour, set the $govuk-button-text-colour
Sass variable.
@import "node_modules/govuk-frontend/govuk/base";
$govuk-button-background-colour: govuk-colour("yellow");
$govuk-button-text-colour: govuk-colour("black");
@import "node_modules/govuk-frontend/govuk/components/button/index";
This was added in pull request #2752: Change the Button component background and text colour. Thanks to @NickColley for this contribution.
Localise the navigation menu toggle button
When using the header Nunjucks macro, you can now translate the text of the mobile navigation menu toggle button by using the menuButtonText
parameter.
You should avoid lengthy values for the menuButtonText
parameter. If the text is too long it can overflow and cause visual issues.
This was added in pull request #2720: Add parameter to localise mobile menu toggle button.
Localise the character count's textarea description/fallback text
When using the character count Nunjucks macro, you can now translate the description of textarea by using the textareaDescriptionText
option.
This text is announced by screen readers when the character count input is focused. It's also displayed visually as a fallback if JavaScript is not available.
This was added in pull request #2742: Add ability to customise character count fallback text, and the option renamed to textareaDescriptionText
in pull request #2915.
Localise the character count's counter message
You can now translate the text shown by the character count component to inform users of:
- when they have reached the maximum number of characters or words
- the number of characters or words over or under the allowed maximum
The Nunjucks macro accepts new options so you can customise each message. You can:
- Use
charactersAtLimitText
orwordsAtLimitText
to provide the text that shows when users have reached the limit. - Use
charactersUnderLimitText
orwordsUnderLimitText
to provide the text that shows when users are under the limit. The component will pluralise the message according to the configured locale and the number of characters or words remaining. - Use
charactersOverLimitText
orwordsOverLimitText
to provide the text that shows when users are over the limit. The component will pluralise the message according to the configured locale and the number of characters or words remaining.
You'll find guidance about the plural forms in our documentation about localising GOV.UK Frontend. The component will replace %{count}
with the number of characters over or under the limit.
If you're not using Nunjucks macros, you can use data-* attributes to provide these translations. Within the attribute value, any quotation marks or other characters reserved by HTML needs to be converted into their HTML entity equivalents.
You can:
- use
data-i18n.characters-at-limit
ordata-i18n.words-at-limit
for when users are at the limit - configure the text that informs the end user they are under the character or word limit, by using
data-i18n.characters-under-limit.{other,many,few,two,one,zero}
ordata-i18n.words-under-limit.{other,many,few,two,one,zero}
, with one suffix for each plural form required by your locale - configure the text that informs the end user they are over the character or word limit, by using
data-i18n.characters-over-limit.{other,many,few,two,one,zero}
ordata-i18n.words-over-limit.{other,many,few,two,one,zero}
, with one suffix for each plural form required by your locale
You can also provide these messages using a JavaScript configuration object when creating an instance of the component or initialising all components. See our guidance on localising GOV.UK Frontend for how to do this.
This was added in the following pull requests:
- #2895 Add macro options to configure CharacterCount translations
- #2887 Allow CharacterCount component to receive i18n config via JS
Localise the character count's input description for assistive technologies
When configuring the character count's limit in JavaScript, you can customise the description provided to assistive technologies when users focus the input (so it indicates the overall limit of characters or words).
Depending on the plural form required by your locale, you can pass the description in the HTML using the data-i18n.textarea-description.{other,many,few,two,one,zero}
attribute on the element to provide the text to set as the description.
You can also provide these messages using a JavaScript configuration object when creating an instance of the component or initialising all components. See our guidance on localising GOV.UK Frontend for how to do this.
This was added in pull request #2915.
Localise the accordion's toggle buttons
You can now translate the text of the accordion component's show and hide toggle buttons.
When using the Nunjucks macro, you can use the new showSectionText
and hideSectionText
parameters to customise the text of the 'show' and 'hide' toggles in each section.
You can also use showAllSectionsText
and hideAllSectionsText
parameters to customise the text of the toggle at the top of the accordion.
If you're not using the Nunjucks macro, you can customise these using data-* attributes. Within the attribute value, any quotation marks or other characters reserved by HTML needs to be converted into their HTML entity equivalents.
data-i18n.show-section
data-i18n.show-section-aria-label
data-i18n.hide-section
data-i18n.hide-section-aria-label
data-i18n.show-all-sections
data-i18n.hide-all-sections
You can also change this text for all instances of the Accordion using a JavaScript configuration object. See our guidance on localising GOV.UK Frontend for how to do this.
This was added in pull requests:
- #2818: Add support for localisation via data-* attributes to Accordion component
- #2826: Add support for localisation via JavaScript configuration to Accordion component
Suppress deprecation warnings
You can now suppress warnings from deprecations within GOV.UK Frontend by updating the $govuk-suppressed-warnings
map in Sass. Every deprecation warning will now include a warning "key" which you can use in the following code, placed at the root of your sass project:
$govuk-suppressed-warnings: (
deprecated-feature
);
This was added in #2911 Add warning suppression functionality
Configure components in JavaScript
JavaScript components can get the same configuration options in 2 ways - through data attributes, as before, and now when creating an instance. These components are:
- the
Button
component, for itspreventDoubleClick
option (matchingdata-prevent-double-click
) - the
CharacterCount
component, for itsmaxlength
,maxwords
andthreshold
options (matchingdata-maxlength
,data-maxwords
anddata-threshold
, respectively) - the
ErrorSummary
component, for itsdisableAutoFocus
option (matchingdata-disable-auto-focus
) - the
NotificationBanner
component, for itsdisableAutoFocus
option (matchingdata-disable-auto-focus
)
You can leave out these configuration options when using the Nunjucks macro and provide configuration when:
- creating a component, in a configuration object as second argument
- initialising components in bulk using
initAll
For example:
// Creating a single instance
var button = document.querySelector('[data-module="button"]')
new GOVUKFrontend.Button(button, {preventDoubleClick: true})
// Or initialising components in bulk
GOVUKFrontend.initAll({
button: {
preventDoubleClick: true
}
// Or, for the other components,
// characterCount: {/* options */},
// errorSummary: {/* options */},
// notificationBanner: {/* options */}
})
You can find more information about component configuration in GOV.UK Frontend documentation.
This was added in pull requests specific for each components:
- NotificationBanner – #2843
- [ErrorSummary – #2854](https://github.c...