govuk-frontend
Advanced tools
Changelog
3.0.0 (Breaking release)
You must make the following changes when you migrate to this release, or your service may break.
To make sure GOV.UK Frontend's files do not conflict with your code, we've moved our package files into a directory called govuk.
Add govuk/ after govuk-frontend/ to @import paths in your Sass file.
For example:
@import "node_modules/govuk-frontend/govuk/all";
If you’ve added node_modules/govuk-frontend as a Sass include path, add govuk/ to your @import paths:
@import "govuk/all";
You must do the following.
data-module attributes.You must add govuk/ to your import paths.
If you're importing node_modules/govuk-frontend/all.js, change this import path to node_modules/govuk-frontend/govuk/all.js.
If you’re importing a specific path, add govuk/ after govuk-frontend/. For example, if you're importing the button component:
import Button from 'govuk-frontend/govuk/components/button/button'
You do not need to do anything if you're using Nunjucks macros and the initAll function.
If you are not using Nunjucks macros, add a govuk- prefix to data-module attribute values. For example:
<div class="govuk-accordion" data-module="govuk-accordion">
...
</div>
The button and details components now also use the data-module attribute for initialisation. If you are not using Nunjucks macros, add:
data-module="govuk-button" to each <button> HTML tagdata-module="govuk-details" to each <details> HTML tagIf you're using your own JavaScript code to initialise components, add a govuk- prefix to any selectors that find components using the data-module attribute.
Pull request #1443: Ensure GOV.UK Frontend component selectors cannot conflict when initialised
You do not need to do anything if you're using Nunjucks.
If you're using HTML or custom JavaScript, change:
js-character-count to govuk-js-character-countjs-header-toggle in the GOV.UK Frontend header component to govuk-js-header-togglePull request #1444: Renames js- css prefix to govuk-js-
nunjucks.configure so that the only GOV.UK Frontend path is node_modules/govuk-frontend/:nunjucks.configure([
"node_modules/govuk-frontend/"
])
govuk/ to the template path:{% extends "govuk/template.njk" %}
govuk/components/. For example:{% from "govuk/components/breadcrumbs/macro.njk" import govukBreadcrumbs %}
In the assets path, add govuk/ after govuk-frontend/:
/node_modules/govuk-frontend/govuk/assets
If your code uses Express.js, you must also use the following code in your configuration file:
app.use('/assets', express.static(path.join(__dirname, '/node_modules/govuk-frontend/govuk/assets')))
Pull requests:
The focus state of components now meets the new WCAG 2.1 level AA requirements.
You must update your component’s focus state to make your design consistent with our new focus styles.
If you've extended or created components, you can no longer use the govuk-focusable or govuk-focusable-fill Sass mixins.
If you're using govuk-focusable, you must remove it. There’s no direct replacement, so you must use our Sass variables to make your components consistent with GOV.UK Frontend.
If you're using govuk-focusable-fill, include the govuk-focused-text mixin inside your component's :focus selector. For example:
.app-component:focus {
@include govuk-focused-text;
}
Pull requests:
govuk-focusable, govuk-focusable-fill mixins, introduce govuk-focus-text mixinYou can now use the following new colour variables that we've added to the colour palette:
5 Sass colour variables no longer exist. Replace the following colour variables if you're using Sass:
| Colour variable removed | Suggested replacement | | ----------------------- | --------------------- | | bright-red | red | | grey-1 | dark-grey | | grey-2 | mid-grey | | grey-3 | light-grey | | grey-4 | light-grey |
You should check the contrast ratio of your colours.
If you're not using Sass, change the values of the following colours:
| Colour name | Old value | Replace with | | ----------- | --------- | ------------ | | purple | #2e358b | #4c2c92 | | red | #b10e1e | #d4351c | | yellow | #ffbf47 | #ffdd00 | | green | #006435 | #00703c | | grey-2 | #bfc1c3 | #b1b4b6 | | grey-3 | #dee0e2 | #f3f2f1 | | grey-4 | #f8f8f8 | #f3f2f1 | | light-blue | #2b8cc4 | #5694ca | | blue | #005ea5 | #1d70b8 | | bright-red | #df3034 | #d4351c |
We've also changed the background of the following components:
green instead of a custom greengreen instead of turquoisedark-blue instead of light-blueIf you're using legacy projects like GOV.UK Elements, you can keep your current colours by turning on compatibility mode.
Read our blog post about why we changed the colour palette
Pull request #1288: Update colour palette.
The size and baseline of the Design System's font are now more consistent with other fonts. Text now aligns vertically in text boxes without you needing to adjust it.
If you've extended or created components, you should check that your text is still vertically aligned correctly.
If you're using GOV.UK Frontend and GOV.UK Template, you can turn on compatibility mode to keep using the font from GOV.UK Template.
Pull requests:
If you've linked from an error summary component to the first input in a radios or checkboxes component, the link will no longer work.
This is because the id of the first input no longer has the suffix -1.
If there are links back to radios or checkboxes components in your error summary component, remove -1 from the end of the href attribute.
Pull request #1426: Make radios and checkboxes components easier to link to from error summary
You do not need to do anything if you're using Nunjucks macros.
If you are not using Nunjucks macros, remove the govuk-tabs__tab--selected class from the first tab's link, then add the govuk-tabs__list-item--selected class to that link's parent list item.
For example:
<li class="govuk-tabs__list-item govuk-tabs__list-item--selected">
<a class="govuk-tabs__tab" href="#tab1">
Tab 1
</a>
</li>
Pull request #1496: Update the focus state for tabs
Start buttons have a new icon. Your start buttons will lose their current icons unless you replace the old icon with the new one.
If you're using Nunjucks:
isStartButton option to true.govuk-button--start classFor example:
govukButton({
text: "Start now",
href: "#",
isStartButton: true
})
If you're using HTML, add the SVG code from the start button example in the Design System.
Pull request #1341: Add new start button icon
Text now aligns to the top of table cells. If you've used a different alignment in a table, you should use your own CSS styles to keep the alignment the same.
For example, to align text in the centre:
.app-table--vertical-align-middle .govuk-table__header,
.app-table--vertical-align-middle .govuk-table__cell {
vertical-align: middle;
...
}
Pull request #1345: Set 'vertical-align:top' positioning on table headers and cells
If you're using the @govuk-grid-column Sass mixin to create custom grid classes, you must remove the $class parameter.
If you're passing a class name, put the mixin inside your selector. For example:
.your-class-name {
@include govuk-grid-column(...)
}
You can no longer use the govuk-grid-row mixin. You can replace it with the .govuk-grid-row class in your HTML.
You must also replace calls to the grid-width mixin with calls to the govuk-grid-width mixin.
Pull requests:
If you use Sass and you’ve extended or created components that use the border width variable, rename $govuk-border-width-mobile to $govuk-border-width-narrow.
Pull request #1287: Rename border-width-mobile to reflect how it's used
You can now add attributes like classes, rowspan and colspan to table row headers.
Pull request #1367: Allow for classes, rowspan, colspan and attributes on row headers. Thanks to edwardhorsford.
You can now add the .govuk-main-wrapper--auto-spacing modifier class to your <main> element to add responsive padding to the top and bottom of the page.
This will add the correct amount of padding depending on if there are elements above the <main> element inside the govuk-width-container wrapper. Elements above the <main> element could include a back link or breadcrumb component.
If you need to control the spacing manually, use the .govuk-main-wrapper--l modifier instead.
The govuk-main-wrapper and govuk-main-wrapper--l Sass mixins are now deprecated. Contact us if you need to continue using these mixins.
Pull request #1493: Add automatic vertical spacing modifier for main wrapper
IE8 will now use Arial instead of GDS Transport.
This is because IE8 requires a very large Embedded Open Type (.eot) font file for external fonts. Arial will take less time to render for IE8 users, who are likely to be on older computers.
Pull request #1434: Update font to use v2 of GOV.UK Transport font. Thanks to @Nooshu.
productName and serviceName in the header component - thanks to @edwardhorsford.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/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 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.
The npm package govuk-frontend receives a total of 98,804 weekly downloads. As such, govuk-frontend popularity was classified as popular.
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.
Product
Socket now supports four distinct alert actions instead of the previous two, and alert triaging allows users to override the actions taken for all individual alerts.
Security News
Polyfill.io has been serving malware for months via its CDN, after the project's open source maintainer sold the service to a company based in China.
Security News
OpenSSF is warning open source maintainers to stay vigilant against reputation farming on GitHub, where users artificially inflate their status by manipulating interactions on closed issues and PRs.