govuk-frontend
Advanced tools
Changelog
5.0.0 (Breaking release)
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).
You must make the following changes when you migrate to this release, or your service might break.
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
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:
govuk-frontend
via local packagedist
and package
from sourceIn 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
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.application.config.assets.paths
append_path
These changes were introduced in #3498: Remove built dist
and package
from source
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
Changelog
4.7.0 (Feature release)
Note: This release was created from the support/4.x
branch.
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.
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.
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.
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.
We’ve made fixes to GOV.UK Frontend in the following pull requests:
Changelog
4.6.0 (Feature release)
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.
disabled
parameter to form controlsWe’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.
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.
id
parameter to ButtonsWe’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 Tom Billington for this contribution.
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
init
methodWe 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.
.govuk-button--disabled
class on buttonsWe 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.
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:
govuk-if-ie8
and govuk-not-ie8
mixins in your own Sass code (for example @include govuk-if-ie8
)$govuk-is-ie8
and $govuk-ie8-breakpoint
settings to anything other than their default valuesIf 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.
We’ve made fixes to GOV.UK Frontend in the following pull requests:
Changelog
4.5.0 (Feature release)
You can now use the summary card. This new variant of the Summary list component can help you:
This was added in pull request #2931: Add summary card enhancement to summary list.
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:
hidden='until-found'
.js-enabled
page loadYou 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.
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:
We've made fixes to GOV.UK Frontend in the following pull requests:
classList
polyfill from header component JavaScriptEvent
polyfill to accordion component JavaScriptChangelog
4.4.1 (Fix release)
Note: This release was created from the support/4.4.x
branch.
We've made fixes to GOV.UK Frontend in the following pull requests:
Changelog
4.4.0 (Feature release)
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 Nick Colley for this contribution.
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.
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.
You can now translate the text shown by the character count component to inform users of:
The Nunjucks macro accepts new options so you can customise each message. You can:
charactersAtLimitText
or wordsAtLimitText
to provide the text that shows when users have reached the limit.charactersUnderLimitText
or wordsUnderLimitText
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.charactersOverLimitText
or wordsOverLimitText
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:
data-i18n.characters-at-limit
or data-i18n.words-at-limit
for when users are at the limitdata-i18n.characters-under-limit.{other,many,few,two,one,zero}
or data-i18n.words-under-limit.{other,many,few,two,one,zero}
, with one suffix for each plural form required by your localedata-i18n.characters-over-limit.{other,many,few,two,one,zero}
or data-i18n.words-over-limit.{other,many,few,two,one,zero}
, with one suffix for each plural form required by your localeYou 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:
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.
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:
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
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:
Button
component, for its preventDoubleClick
option (matching data-prevent-double-click
)CharacterCount
component, for its maxlength
, maxwords
and threshold
options (matching data-maxlength
, data-maxwords
and data-threshold
, respectively)ErrorSummary
component, for its disableAutoFocus
option (matching data-disable-auto-focus
)NotificationBanner
component, for its disableAutoFocus
option (matching data-disable-auto-focus
)You can leave out these configuration options when using the Nunjucks macro and provide configuration when:
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:
If you're not using the Nunjucks macros, you can improve the experience for screen reader users by making these changes to the error summary markup:
aria-labelledby="error-summary-title"
and role="alert"
from the parent element (govuk-error-summary
)div
wrapper around the contents of govuk-error-summary
with the attribute role="alert"
id="error-summary-title"
from the error summary h2
(govuk-error-summary__title
)This will enable screen reader users to have a better, more coherent experience with the error summary. It will make sure users of JAWS 2022 or later will hear the entire contents of the error summary on page load and therefore have further context on why there is an error on the page they're on.
This was added in pull request #2677: Amend error summary markup to fix page load focus bug in JAWS 2022.
In GOV.UK Frontend v5.0 we will stop supporting compatibility with legacy codebases. We are therefore deprecating the compatibility mode variables associated with legacy codebases:
$govuk-compatibility-govukfrontendtoolkit
$govuk-compatibility-govuktemplate
$govuk-compatibility-govukelements
This was introduced in pull request #2882: Deprecate compatibility mode settings.
In GOV.UK Frontend v5.0 we will stop supporting compatibility with legacy codebases. As part of this, we're deprecating settings controlled by compatibility mode variables. This includes the govuk-compatibility
mixin and the following settings:
$govuk-use-legacy-palette
$govuk-use-legacy-font
$govuk-typography-use-rem
$govuk-font-family-tabular
This was introduced in pull request #2844: Remove compatibility mode from govuk-frontend.
In pull request 2851: Support Prototype Kit v13 we've introduced support for the plugins system included in the upcoming Prototype Kit v13.
We've made fixes to GOV.UK Frontend in the following pull requests: