govuk-frontend
Advanced tools
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-sectiondata-i18n.show-section-aria-labeldata-i18n.hide-sectiondata-i18n.hide-section-aria-labeldata-i18n.show-all-sectionsdata-i18n.hide-all-sectionsYou 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:
initAllFor 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-govukelementsThis 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-tabularThis 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:
Readme
GOV.UK Frontend contains the code you need to start building a user interface for government platforms and services.
See live examples of GOV.UK Frontend components, and guidance on when to use them in your service, in the GOV.UK Design System.
GOV.UK Frontend is maintained by a team at Government Digital Service. If you want to know more about GOV.UK Frontend, please email the Design System team or get in touch with them on Slack.
There are 2 ways to start using GOV.UK Frontend in your app.
Once installed, you will be able to use the code from the examples in the GOV.UK Design System in your service.
We recommend installing GOV.UK Frontend using node package manager (npm).
You can also download the compiled and minified assets (CSS, JavaScript) from GitHub.
You need to import the GOV.UK Frontend styles into the main Sass file in your project. You should place the below code before your own Sass rules (or Sass imports) if you want to override GOV.UK Frontend with your own styles.
To import add the below to your Sass file:
@import "node_modules/govuk-frontend/govuk/all";
More details on importing styles
Some of the JavaScript included in GOV.UK Frontend improves the usability and accessibility of the components. You should make sure that you are importing and initialising Javascript in your application to ensure that all users can use it successfully.
You can include Javascript for all components either by copying the all.js from node_modules/govuk-frontend/govuk/ into your application or referencing the file directly:
<script src="<path-to-govuk-frontend-all-file>/all.js"></script>
Next you need to initialise the script by adding:
<script>window.GOVUKFrontend.initAll()</script>
More details on importing Javascript and advanced options
In order to import GOV.UK Frontend images and fonts to your project, you should configure your application to reference or copy the relevant GOV.UK Frontend assets.
More details on importing assets
To be notified when there’s a new release, you can either:
Find out how to update with npm.
Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation. The documentation is © Crown copyright and available under the terms of the Open Government 3.0 licence.
If you want to help us build GOV.UK Frontend, view our contribution guidelines.
FAQs
GOV.UK Frontend contains the code you need to start building a user interface for government platforms and services.
We found that govuk-frontend demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In an unprecedented surge, May 2024 saw the publication of over 5,000 CVEs, marking a historic milestone in cybersecurity with an average of 164 CVEs per day, nearly double the 2023 daily average.
Security News
The White House is addressing fragmented cybersecurity regulations as CISOs report spending up to 50% of their time on compliance, aiming to harmonize requirements and improve cybersecurity outcomes.
Security News
Research
The Socket Research Team has identified a malicious Python package that is typosquatting the popular crytic-compile utility, frequently used in popular toolkits and development environments for smart contracts and crypto applications.