How to guides

Updating your code

GOV.UK Frontend is the frontend codebase that replaces GOV.UK Elements, Frontend Toolkit and parts of GOV.UK Template.

The tables below show the old and new names for components, classes and mixins, to help you find what you need.

Page template

Previously, to keep your pages consistent with the rest of GOV.UK you would have needed to use GOV.UK Template.

This has been brought into GOV.UK Frontend. You can consume it using Nunjucks or HTML.

If you are not using Nunjucks you can get the page template HTML.

Nunjucks

Where possible we have kept the new page template the same as GOV.UK Template.

The main change is changing variables from snake_case to camelCase.

Nunjucks Template
GOV.UK Template GOV.UK Frontend
:top_of_page Deprecated: putting content above the <!DOCTYPE html> will result in broken pages for users of older Internet Explorer versions.
:html_lang htmlLang
:page_title pageTitle
:asset_path assetPath
:head head
:body_classes bodyClasses
:body_start bodyStart
:skip_link_message

You can now entirely replace the skip link by rendering your own, which can include custom text

{% block skipLink %}
  {{ govukSkipLink({ text: "custom text" }) }}
{% endblock %}

See the skip link component for more details.

:cookie_message No replacement, we are looking to improve this component based on GDPR requirements.
header_class

You can now entirely replace the header component by rendering your own, which can include custom classes

{% block header %}
    {{ govukHeader({ classes: "app-custom-classes" }) }}
{% endblock %}

See the header component for more details.

homepage_url

You can now entirely replace the header component by rendering your own, which can include custom homepageUrl

{% block header %}
    {{ govukHeader({ homepageUrl: "/custom-url" }) }}
{% endblock %}

See the header component for more details.

global_header_text No equivalent. Raise an issue if you need this.
inside_header

You can now entirely replace the header component by rendering your own, which can include a custom serviceName

{% block header %}
    {{ govukHeader({ serviceName: "Custom service name" }) }}
{% endblock %}

See the header component for more details.

proposition_header

You can now entirely replace the header component by rendering your own, which can include a custom navigation

{% block header %}
    {{ govukHeader({ navigation: [] }) }}
{% endblock %}

See the header component for more details.

:after_header beforeContent
:content

main

Setting content in the new template will put it inside a <main> element.

In the old GOV.UK Template there was no default <main> element.

You can restructure your content so that it doesn't use a <main> element, or override the main block.

:footer_top

You can now entirely replace the footer component by rendering your own, which can include a custom navigation

{% block header %}
    {{ govukFooter({ navigation: [] }) }}
{% endblock %}

See the footer component for more details.

:footer_support_links

You can now entirely replace the footer component by rendering your own, which can include custom meta links

{% block header %}
    {{ govukFooter({ meta: [] }) }}
{% endblock %}

See the footer component for more details.

:licence_message No equivalent. Raise an issue if you need this.
:body_end bodyEnd

Component names

Component names
GOV.UK Elements GOV.UK Frontend
link-back Back link component
Button Button component
Checkboxes Checkboxes component
Date pattern Date input component
Hidden text (Progressive disclosure) Details component
Errors and validation Error message component
Error summary component
<fieldset> Fieldset component
File upload File upload component
Alpha and beta banners Phase banner component
Radio buttons Radios component
Select boxes Select component
Phase tag Tag component
Form fields Text input component
<textarea> Textarea component
Warning text (previously Legal text) Warning text component
govuk-box-highlight Panel component
Inset text Inset text component
panel (object)
panel-border-wide
panel-border-narrow
Deprecated: this style is now contained within each component that needs it

Class names

GOV.UK Frontend uses “Block, Element, Modifier” (BEM) and Inverted Triangle CSS (ITCSS) to structure CSS and define class names. This means all of the existing class names have changed.

Typography class names

Typography class names
GOV.UK Elements GOV.UK Frontend
heading-xlarge govuk-heading-xl
heading-large govuk-heading-l
heading-medium govuk-heading-m
heading-small govuk-heading-s
lede govuk-body-l
<p>
body-text
govuk-body
font-xsmall govuk-body-s
<a> govuk-link
<hr> govuk-section-break
govuk-section-break--visible
govuk-section-break--xl
govuk-section-break--l
govuk-section-break--m

Lists

Lists
GOV.UK Elements GOV.UK Frontend
list govuk-list
list
list-bullet
govuk-list
govuk-list--bullet
list
list-number
govuk-list
govuk-list--number

Layout and grid system class names

Grid system class names
GOV.UK Elements GOV.UK Frontend
grid-row govuk-grid-row
column-full govuk-grid-column-full
column-one-half govuk-grid-column-one-half
column-one-third govuk-grid-column-one-third
column-two-thirds govuk-grid-column-two-thirds
column-one-quarter govuk-grid-column-one-quarter
#content Page wrappers
Helper class names
GOV.UK Elements GOV.UK Frontend
form-group govuk-form-group
form-hint Specific to component, for example
govuk-label__hint
form-label Specific to component, for example
govuk-label
govuk-radios__label
form-label-bold govuk-label--s
form-control
form-control-3-4
form-control-2-3
form-control-1-2
form-control-1-3
form-control-1-4
form-control-1-8
Width override classes
form-section Deprecated: not required with new spacing implementation
form-group-related Deprecated: not required with new spacing implementation
form-group-compound Deprecated: not required with new spacing implementation

Helper class names

Helper class names
GOV.UK Elements GOV.UK Frontend
visually-hidden, visuallyhidden govuk-visually-hidden
govuk-visually-hidden-focusable

Override class names

Override class names
GOV.UK Elements GOV.UK Frontend
font-xxlarge govuk-!-font-size-80
font-xlarge govuk-!-font-size-48
font-large govuk-!-font-size-36
font-medium govuk-!-font-size-24
font-small govuk-!-font-size-19
font-xsmall govuk-!-font-size-16
bold-xxlarge govuk-!-font-size-80
govuk-!-font-weight-bold
bold-xlarge govuk-!-font-size-48
govuk-!-font-weight-bold
bold-large govuk-!-font-size-36
govuk-!-font-weight-bold
bold-medium govuk-!-font-size-24
govuk-!-font-weight-bold
bold-small govuk-!-font-size-19
govuk-!-font-weight-bold
bold-xsmall govuk-!-font-size-16
govuk-!-font-weight-bold
bold govuk-!-font-weight-bold

Mixins

Typography

Helper class names
GOV.UK Frontend Toolkit GOV.UK Frontend
@include core-80 @include govuk-font(80)
@include core-48 @include govuk-font(48)
@include core-36 @include govuk-font(36)
@include core-27 @include govuk-font(27)
@include core-24 @include govuk-font(24)
@include core-19 @include govuk-font(19)
@include core-16 @include govuk-font(16)
@include core-14 @include govuk-font(14)
@include bold-80 @include govuk-font(80, $weight: bold)
@include bold-48 @include govuk-font(48, $weight: bold)
@include bold-36 @include govuk-font(36, $weight: bold)
@include bold-27 @include govuk-font(27, $weight: bold)
@include bold-24 @include govuk-font(24, $weight: bold)
@include bold-19 @include govuk-font(19, $weight: bold)
@include bold-16 @include govuk-font(16, $weight: bold)
@include bold-14 @include govuk-font(14, $weight: bold)
@include heading-80 Deprecated: 80px headings are not used, @include govuk-font(80, $weight: bold) should be used instead
@include heading-48 @extend %govuk-heading-xl
@include heading-36 @extend %govuk-heading-l
@include heading-27 Deprecated: 27px headings are not used, @include govuk-font(27, $weight: bold) should be used instead
@include heading-24 @extend %govuk-heading-m
@include copy-19 @extend %govuk-body
@include copy-14 @extend %govuk-body-xs

Layout

Helper class names
GOV.UK Frontend Toolkit GOV.UK Frontend
@extend site-width-container @include govuk-width-container
@include grid-column( 1/4 ) Deprecated: you can’t apply grid properties to other elements using GOV.UK Frontend
@include grid-column( 1/2 ) Deprecated: you can’t apply grid properties to other elements using GOV.UK Frontend
@include grid-column( 1/3 ) Deprecated: you can’t apply grid properties to other elements using GOV.UK Frontend
@include grid-column( 2/3 ) Deprecated: you can’t apply grid properties to other elements using GOV.UK Frontend
@include grid-column( 1/3, $full-width: desktop ); Deprecated: you can’t apply grid properties to other elements using GOV.UK Frontend

Media queries

Helper class names
GOV.UK Frontend Toolkit GOV.UK Frontend
@include media(desktop) @include govuk-media-query($from: desktop)
@include govuk-media-query($until: desktop)
@include media(tablet) @include govuk-media-query($from: tablet)
@include govuk-media-query($until: tablet)
@include media(mobile) @include govuk-media-query($from: mobile)
@include govuk-media-query($until: mobile)

Images

Helper class names
GOV.UK Frontend Toolkit GOV.UK Frontend
@include device-pixel-ratio($ratio: 2) @include govuk-device-pixel-ratio($ratio: 2)

Shims

Helper class names
GOV.UK Frontend Toolkit GOV.UK Frontend
@include inline-block Deprecated: inline-block is now the default for any components
@extend contain-floats @include govuk-clearfix

Internet Explorer

Helper class names
GOV.UK Frontend Toolkit GOV.UK Frontend
@include ie-lte(8) @include govuk-ie-lte(8)
@include ie(6) @include govuk-ie(6)

Get in touch

If you’ve got a question, idea or suggestion share it in #govuk-design-system on cross-government Slack (open in app) or email the Design System team on govuk-design-system-support@digital.cabinet-office.gov.uk