Skip to main content

Sass API reference

Settings

Assets

$govuk-assets-path

Path to the assets directory, with trailing slash.

This is the directory where the images and fonts subdirectories live. You will need to make this directory available via your application – see the README for details.

Default value
$govuk-assets-path: "/assets/";

View source code for _assets.scss on GitHub

$govuk-images-path

Path to the images folder, with trailing slash.

Default value
$govuk-images-path: "#{$govuk-assets-path}images/";

View source code for _assets.scss on GitHub

$govuk-fonts-path

Path to the fonts folder, with trailing slash.

Default value
$govuk-fonts-path: "#{$govuk-assets-path}fonts/";

View source code for _assets.scss on GitHub

$govuk-image-url-function

Custom image URL function

If the built-in image URL helper does not meet your needs, you can specify the name of a custom handler – either built in or by writing your own function.

If you are writing your own handler, ensure that it returns a string wrapped with url()

Default value
$govuk-image-url-function: false;
Example: Rails asset handling
$govuk-image-url-function: 'image-url';
Example: Custom asset handling
@function my-url-handler($filename) {
  // Some custom URL handling
  @return url('example.jpg');
}

$govuk-image-url-function: 'my-url-handler';

View source code for _assets.scss on GitHub

$govuk-font-url-function

Custom font URL function

If the built-in font URL helper does not meet your needs, you can specify the name of a custom handler – either built in or by writing your own function.

If you are writing your own handler, ensure that it returns a string wrapped with url()

Default value
$govuk-font-url-function: false;
Example: Rails asset handling
$govuk-font-url-function: 'font-url';
Example: Custom asset handling
@function my-url-handler($filename) {
  // Some custom URL handling
  @return url('example.woff');
}

$govuk-font-url-function: 'my-url-handler';

View source code for _assets.scss on GitHub

Colours

$govuk-default-functional-colours

Default definitions of the functional colours

Default value
$govuk-default-functional-colours: (
  (
    "brand": (
      name: "blue"
    ),
    "text": (
      name: "black"
    ),
    // The background colour of the template. This is intended to be the same
    // as `surface-background` for the purposes of making the Footer and Cookie
    // banner components merge seamlessly with the template.
    "template-background": (
        name: "blue",
        variant: "tint-95"
      ),
    "body-background": (
      name: "white"
    ),
    // Use 'true black' to avoid printers using colour ink to print body text
    "print-text": #000000,
    // Used in for example 'muted' text and help text.
    "secondary-text": (
        name: "black",
        variant: "tint-25"
      ),
    // Used for outline (and background, where appropriate) when interactive
    // elements (links, form controls) have keyboard focus.
    "focus": (
        name: "yellow"
      ),
    // Ensure that the contrast between the text and background colour passes
    // WCAG Level AA contrast requirements.
    "focus-text": (
        name: "black"
      ),
    // Used to highlight error messages and form controls in an error state
    "error": (
        name: "red"
      ),
    // Used to highlight success messages and banners
    "success": (
        name: "green"
      ),
    // Used in for example borders, separators, rules and keylines.
    "border": (
        name: "black",
        variant: "tint-80"
      ),
    // Used for form inputs and controls
    "input-border": (
        name: "black"
      ),
    // Used for hover states on form controls
    "hover": (
        name: "black",
        variant: "tint-80"
      ),
    // Standard links (on white)
    "link": (
        name: "blue",
        variant: "shade-10"
      ),
    "link-visited": (
      name: "purple"
    ),
    "link-hover": (
      name: "blue",
      variant: "shade-50"
    ),
    "link-active": (
      name: "black"
    ),
    // 'Surfaces' are our name for components that have different colour
    // palettes to typical page content. This is the generic surface.
    "surface-background": (
        name: "blue",
        variant: "tint-95"
      ),
    "surface-text": (
      name: "black"
    ),
    "surface-border": (
      name: "blue",
      variant: "tint-50"
    )
  )
);

View source code for _colours-functional.scss on GitHub

$govuk-functional-colours

Functional colours for the GOV.UK palette.

Each functional colour is represented by a name (for example 'brand') to which the map associates either:

  • a Sass colour (like #1d70b8)
  • a Sass map with a name and an optional variant properties, referring to one of the colours in the colour palette (like (name: 'blue', variant: 'primary')). variant defaults to 'primary' if omitted.

Use the govuk-functional-colour function to access these colours.

Customise functional colours by defining $govuk-functional-colours with a map of the colours that you want to change before importing GOV.UK Frontend. These will then be merged with the default colours. You can only redefine existing colours.

Default value
$govuk-functional-colours: $govuk-default-functional-colours;
Example: – Redefining functional colours by setting them before import
// These will be merged with the default functional colours
$govuk-functional-colours: (
  // set the 'brand' colour to the 'primary' variant of 'purple'
  brand: (name: 'purple'),
  // set the 'template-background' colour to the 'tint-95' variant of 'purple'
  template-background: (name: 'purple', variant: 'tint-95'),
  // set the 'text' colour to an arbitrary colour `#221133`
  text: #221133
);

View source code for _colours-functional.scss on GitHub

$govuk-brand-colour

Brand colour

Usage
Warning

Deprecated: Variables for applied colours are deprecated. Please use the govuk-functional-colour function instead: govuk-functional-colour(brand).
Default value
$govuk-brand-colour: govuk-functional-colour(brand);

View source code for _colours-functional.scss on GitHub

$govuk-text-colour

Text colour

Usage
Warning

Deprecated: Variables for applied colours are deprecated. Please use the govuk-functional-colour function instead: govuk-functional-colour(text).
Default value
$govuk-text-colour: govuk-functional-colour(text);

View source code for _colours-functional.scss on GitHub

$govuk-template-background-colour

Template background colour

Used by components that want to give the illusion of extending the template background (such as the footer and cookie banner).

Usage
Warning

Deprecated: Variables for applied colours are deprecated. Please use the govuk-functional-colour function instead: govuk-functional-colour(template-background).
Default value
$govuk-template-background-colour: govuk-functional-colour(template-background);

View source code for _colours-functional.scss on GitHub

$govuk-body-background-colour

Body background colour

Usage
Warning

Deprecated: Variables for applied colours are deprecated. Please use the govuk-functional-colour function instead: govuk-functional-colour(body-background).
Default value
$govuk-body-background-colour: govuk-functional-colour(body-background);

View source code for _colours-functional.scss on GitHub

$govuk-print-text-colour

Text colour for print media

Use ‘true black’ to avoid printers using colour ink to print body text

Usage
Warning

Deprecated: Variables for applied colours are deprecated. Please use the govuk-functional-colour function instead: govuk-functional-colour(print-text).
Default value
$govuk-print-text-colour: govuk-functional-colour(print-text);

View source code for _colours-functional.scss on GitHub

$govuk-secondary-text-colour

Secondary text colour

Used in for example ‘muted’ text and help text.

Usage
Warning

Deprecated: Variables for applied colours are deprecated. Please use the govuk-functional-colour function instead: govuk-functional-colour(secondary-text).
Default value
$govuk-secondary-text-colour: govuk-functional-colour(secondary-text);

View source code for _colours-functional.scss on GitHub

$govuk-focus-colour

Focus colour

Used for outline (and background, where appropriate) when interactive elements (links, form controls) have keyboard focus.

Usage
Warning

Deprecated: Variables for applied colours are deprecated. Please use the govuk-functional-colour function instead: govuk-functional-colour(focus).
Default value
$govuk-focus-colour: govuk-functional-colour(focus);

View source code for _colours-functional.scss on GitHub

$govuk-focus-text-colour

Focused text colour

Ensure that the contrast between the text and background colour passes WCAG Level AA contrast requirements.

Usage
Warning

Deprecated: Variables for applied colours are deprecated. Please use the govuk-functional-colour function instead: govuk-functional-colour(focus-text).
Default value
$govuk-focus-text-colour: govuk-functional-colour(focus-text);

View source code for _colours-functional.scss on GitHub

$govuk-error-colour

Error colour

Used to highlight error messages and form controls in an error state

Usage
Warning

Deprecated: Variables for applied colours are deprecated. Please use the govuk-functional-colour function instead: govuk-functional-colour(error).
Default value
$govuk-error-colour: govuk-functional-colour(error);

View source code for _colours-functional.scss on GitHub

$govuk-success-colour

Success colour

Used to highlight success messages and banners

Usage
Warning

Deprecated: Variables for applied colours are deprecated. Please use the govuk-functional-colour function instead: govuk-functional-colour(error).
Default value
$govuk-success-colour: govuk-functional-colour(success);

View source code for _colours-functional.scss on GitHub

$govuk-border-colour

Border colour

Used in for example borders, separators, rules and keylines.

Usage
Warning

Deprecated: Variables for applied colours are deprecated. Please use the govuk-functional-colour function instead: govuk-functional-colour(border).
Default value
$govuk-border-colour: govuk-functional-colour(border);

View source code for _colours-functional.scss on GitHub

$govuk-input-border-colour

Input border colour

Used for form inputs and controls

Usage
Warning

Deprecated: Variables for applied colours are deprecated. Please use the govuk-functional-colour function instead: govuk-functional-colour(input-border).
Default value
$govuk-input-border-colour: govuk-functional-colour(input-border);

View source code for _colours-functional.scss on GitHub

$govuk-hover-colour

Input hover colour

Used for hover states on form controls

Usage
Warning

Deprecated: Variables for applied colours are deprecated. Please use the govuk-functional-colour function instead: govuk-functional-colour(hover).
Default value
$govuk-hover-colour: govuk-functional-colour(hover);

View source code for _colours-functional.scss on GitHub

Link colour

Warning

Deprecated: Variables for applied colours are deprecated. Please use the govuk-functional-colour function instead: govuk-functional-colour(link).

 
$govuk-link-colour: govuk-functional-colour(link);

View source code for _colours-functional.scss on GitHub

Visited link colour

Warning

Deprecated: Variables for applied colours are deprecated. Please use the govuk-functional-colour function instead: govuk-functional-colour(link-visited).

 
$govuk-link-visited-colour: govuk-functional-colour(link-visited);

View source code for _colours-functional.scss on GitHub

Link hover colour

Warning

Deprecated: Variables for applied colours are deprecated. Please use the govuk-functional-colour function instead: govuk-functional-colour(link-hover).

 
$govuk-link-hover-colour: govuk-functional-colour(link-hover);

View source code for _colours-functional.scss on GitHub

Active link colour

Warning

Deprecated: Variables for applied colours are deprecated. Please use the govuk-functional-colour function instead: govuk-functional-colour(link-active).

 
$govuk-link-active-colour: govuk-functional-colour(link-active);

View source code for _colours-functional.scss on GitHub

$govuk-colours-organisations

Organisation colour palette

Default value
$govuk-colours-organisations: (
  "attorney-generals-office": (
    colour: #a91c8e
  ),
  "cabinet-office": (
    colour: #0056b8
  ),
  "civil-service": (
    colour: #b2292e
  ),
  "department-for-business-trade": (
    colour: #e52d13,
    contrast-safe: #e02c13
  ),
  "department-for-culture-media-sport": (
    colour: #ed1588,
    contrast-safe: #d6177a
  ),
  "department-for-education": (
    colour: #003764
  ),
  "department-for-energy-security-net-zero": (
    colour: #003479
  ),
  "department-for-environment-food-rural-affairs": (
    colour: #00a33b,
    contrast-safe: #008531
  ),
  "department-for-science-innovation-technology": (
    colour: #00f8f8,
    contrast-safe: #008180
  ),
  "department-for-transport": (
    colour: #006853
  ),
  "department-for-work-pensions": (
    colour: #00bcb5,
    contrast-safe: #00857e
  ),
  "department-of-health-social-care": (
    colour: #00a990,
    contrast-safe: #008674
  ),
  "foreign-commonwealth-development-office": (
    colour: #012069
  ),
  "hm-government": (
    colour: #266ebc
  ),
  "hm-revenue-customs": (
    colour: #008670
  ),
  "hm-treasury": (
    colour: #b2292e
  ),
  "home-office": (
    colour: #732282
  ),
  "ministry-of-defence": (
    colour: #532a45
  ),
  "ministry-of-housing-communities-local-government": (
    colour: #00625e
  ),
  "ministry-of-justice": (
    colour: #000000
  ),
  "northern-ireland-office": (
    colour: #00205c
  ),
  "office-of-the-advocate-general-for-scotland": (
    colour: #00205c
  ),
  "office-of-the-leader-of-the-house-of-commons": (
    colour: #497629
  ),
  "office-of-the-leader-of-the-house-of-lords": (
    colour: #9c182f
  ),
  "prime-ministers-office-10-downing-street": (
    colour: #0b0c0c
  ),
  "scotland-office": (
    colour: #00205c
  ),
  "serious-fraud-office": (
    colour: #82368c
  ),
  "uk-export-finance": (
    colour: #cf102d
  ),
  "wales-office": (
    colour: #a33038
  )
);

View source code for _colours-organisations.scss on GitHub

Custom properties

$govuk-output-custom-properties

Output CSS custom properties

Whether to output CSS Custom Properties in the compiled stylesheet.

If you are compiling multiple stylesheets that will be used together on a page, set this to false in any secondary stylesheets to avoid including the Custom Properties multiple times.

Default value
$govuk-output-custom-properties: true;

View source code for _custom-properties.scss on GitHub

Global styles

$govuk-global-styles

Include ‘global’ styles

Whether to style paragraphs (<p>) and links (<a>) without explicitly having to apply the govuk-body and govuk-link classes.

Default value
$govuk-global-styles: false;

View source code for _global-styles.scss on GitHub

Layout

$govuk-page-width

Width of main container

Default value
$govuk-page-width: 960px;

View source code for _measurements.scss on GitHub

$govuk-grid-widths

Map of grid column widths

Default value
$govuk-grid-widths: (
  one-quarter: (
    100% / 4
  ),
  one-third: (
    100% / 3
  ),
  one-half: (
    100% / 2
  ),
  two-thirds: (
    200% / 3
  ),
  three-quarters: (
    300% / 4
  ),
  full: 100%
);

View source code for _measurements.scss on GitHub

$govuk-gutter

Width of gutter between grid columns

Default value
$govuk-gutter: 30px;

View source code for _measurements.scss on GitHub

$govuk-gutter-half

Width of half the gutter between grid columns

Default value
$govuk-gutter-half: $govuk-gutter / 2;

View source code for _measurements.scss on GitHub

$govuk-border-width

Standard border width

Default value
$govuk-border-width: 5px;

View source code for _measurements.scss on GitHub

$govuk-border-width-wide

Wide border width

Default value
$govuk-border-width-wide: 10px;

View source code for _measurements.scss on GitHub

$govuk-border-width-narrow

Narrow border width

Default value
$govuk-border-width-narrow: 4px;

View source code for _measurements.scss on GitHub

$govuk-border-width-form-element

Form control border width

Default value
$govuk-border-width-form-element: 2px;

View source code for _measurements.scss on GitHub

$govuk-border-width-form-group-error

Form group border width when in error state

Default value
$govuk-border-width-form-group-error: $govuk-border-width;

View source code for _measurements.scss on GitHub

$govuk-focus-width

Border width of focus outline

Default value
$govuk-focus-width: 3px;

View source code for _measurements.scss on GitHub

$govuk-hover-width

Hover width for form controls with a hover state

Default value
$govuk-hover-width: 10px;

View source code for _measurements.scss on GitHub

$govuk-breakpoints

Breakpoint definitions

Default value
$govuk-breakpoints: (
  mobile: 320px,
  tablet: 641px,
  desktop: 769px
);

View source code for _media-queries.scss on GitHub

Thickness of link underlines

The default will be either:

  • 1px
  • 0.0625rem, if it’s thicker than 1px because the user has changed the text size in their browser

Set this variable to false to avoid setting a thickness.

$govuk-link-underline-thickness: unquote("max(1px, .0625rem)");

View source code for _links.scss on GitHub

Offset of link underlines from text baseline

The default is 3px expressed as ems, as calculated against the default body font size (on desktop) of 19px. 3 ÷ 19 = 0.1578

Set this variable to false to avoid setting an offset.

$govuk-link-underline-offset: 0.1578em;

View source code for _links.scss on GitHub

Thickness of link underlines in hover state

The default for each link will be the thickest of the following:

  • 3px
  • 0.1875rem, if it’s thicker than 3px because the user has changed the text size in their browser
  • 0.12em (relative to the link’s text size)

Set this variable to false to avoid setting a thickness.

$govuk-link-hover-underline-thickness: unquote("max(3px, .1875rem, .12em)");

View source code for _links.scss on GitHub

Typography

$govuk-font-family

Font families to use for all typography on screen media

Default value
$govuk-font-family: "GDS Transport", arial, sans-serif;

View source code for _typography-font.scss on GitHub

$govuk-font-family-print

Font families to use for print media

We recommend that you use system fonts when printing. This will avoid issues with some printer drivers and operating systems.

Default value
$govuk-font-family-print: sans-serif;

View source code for _typography-font.scss on GitHub

$govuk-include-default-font-face

Include the default @font-face declarations

Defaults to true if “GDS Transport” appears in the $govuk-font-family setting.

Default value
$govuk-include-default-font-face: if(index($govuk-font-family, "GDS Transport"), true, false);

View source code for _typography-font.scss on GitHub

$govuk-font-weight-regular

Font weight for regular typography

Default value
$govuk-font-weight-regular: 400;

View source code for _typography-font.scss on GitHub

$govuk-font-weight-bold

Font weight for bold typography

Default value
$govuk-font-weight-bold: 700;

View source code for _typography-font.scss on GitHub

$govuk-root-font-size

Root font size

This is used to calculate rem sizes for the typography, and should match the effective font-size of your root (or html) element.

Ideally you should not be setting the font-size on the html or root element in order to allow it to scale with user-preference, in which case this should be set to 16px.

Default value
$govuk-root-font-size: 16px;

View source code for _typography-responsive.scss on GitHub

$govuk-typography-scale

Responsive typography font map

This is used to generate responsive typography that adapts according to the breakpoints.

Font size and font weight can be defined for each breakpoint. You can define different behaviour on tablet and desktop. The ‘null’ breakpoint is for mobile.

Line-heights will automatically be converted from pixel measurements into relative values. For example, with a font-size of 16px and a line-height of 24px, the line-height will be converted to 1.5 before output.

You can also specify a separate font size and line height for print media.

Default value
$govuk-typography-scale: (
  80: (
    null: (
      font-size: 53px,
      line-height: 55px
    ),
    tablet: (
      font-size: 80px,
      line-height: 80px
    ),
    print: (
      font-size: 53pt,
      line-height: 1.1
    )
  ),
  48: (
    null: (
      font-size: 32px,
      line-height: 35px
    ),
    tablet: (
      font-size: 48px,
      line-height: 50px
    ),
    print: (
      font-size: 32pt,
      line-height: 1.15
    )
  ),
  36: (
    null: (
      font-size: 27px,
      line-height: 30px
    ),
    tablet: (
      font-size: 36px,
      line-height: 40px
    ),
    print: (
      font-size: 24pt,
      line-height: 1.05
    )
  ),
  27: (
    // Made same as 24 on mobile (consider deprecating this size)
    null: (
        font-size: 21px,
        line-height: 25px
      ),
    tablet: (
      font-size: 27px,
      line-height: 30px
    ),
    print: (
      font-size: 18pt,
      line-height: 1.15
    )
  ),
  24: (
    // Bump up mobile size from 18/20 to 21/25
    null: (
        font-size: 21px,
        line-height: 25px
      ),
    tablet: (
      font-size: 24px,
      line-height: 30px
    ),
    print: (
      font-size: 18pt,
      line-height: 1.15
    )
  ),
  19: (
    // Stay at 19/25 at all sizes
    null: (
        font-size: 19px,
        line-height: 25px
      ),
    print: (
      font-size: 14pt,
      line-height: 1.15
    )
  ),
  16: (
    // Stay at 16/20 at all sizes
    null: (
        font-size: 16px,
        line-height: 20px
      ),
    print: (
      font-size: 14pt,
      line-height: 1.2
    )
  )
);

View source code for _typography-responsive.scss on GitHub

Warnings

$govuk-suppressed-warnings

Suppressed warnings map

This map is used to determine which deprecation warnings to not show to users when compiling sass. This is in place for codebases that do not have the necessary capacity to upgrade and remove the deprecation, particularly if the deprecation is significant. For example, the removal of mixins and functions that were previously available to users of Frontend.

You can add to this map and define which warnings to suppress by appending to it using the warning key, found in the warning message. For example:

Default value
$govuk-suppressed-warnings: ();
Example: :
// warning message:
//  $foobar is no longer supported. To silence this warning, update
//  $govuk-suppressed-warnings with key: "foobar"
$govuk-suppressed-warnings: (
  foobar
);

View source code for _warnings.scss on GitHub

Tools

General tools

govuk-exports

Export module

Ensure that the modules of CSS that we define throughout Frontend are only included in the generated CSS once, no matter how many times they are imported across the individual components.

Parameters
Name Description Type Default value
$name Name of module - must be unique within the codebase String
Usage
@include govuk-exports($name) {
  //..
}

View source code for _exports.scss on GitHub

Assets

govuk-font-url

Font URL

If a custom font-url handler is defined ($govuk-font-url-function) then it will be called, otherwise a url will be returned with the filename appended to the font path.

Parameters
Name Description Type Default value
$filename Font filename String

View source code for _font-url.scss on GitHub

govuk-image-url

Image URL

If a custom image-url handler is defined ($govuk-image-url-function) then it will be called, otherwise a url will be returned with the filename appended to the image path.

Parameters
Name Description Type Default value
$Filename for the image to load String

View source code for _image-url.scss on GitHub

Unit conversion

govuk-em

Convert pixels to em

Parameters
Name Description Type Default value
$value Length in pixels Number
$context-font-size Font size of element Number $govuk-root-font-size

View source code for _px-to-em.scss on GitHub

govuk-px-to-rem

Convert pixels to rem

The $govuk-root-font-size (defined in settings/_typography-responsive.scss) must be configured to match the font-size of your root (html) element

Parameters
Name Description Type Default value
$value Length in pixels Number

View source code for _px-to-rem.scss on GitHub

Helpers

General helpers

govuk-device-pixel-ratio

Media query for retina images (device-pixel-ratio)

Parameters
Name Description Type Default value
$ratio Device pixel ratio Number 2
Usage
@include govuk-device-pixel-ratio($ratio: 2) {
  //..
}
Example: Providing a @2x image for screens that support it
background-image: govuk-image-url("my-image.png");

@include govuk-device-pixel-ratio {
  background-image: govuk-image-url("my-image-2x.png");
}
Example: Using a custom ratio
background-image: govuk-image-url("my-image.png");

@include govuk-device-pixel-ratio {
  background-image: govuk-image-url("my-image-2x.png");
}

@include govuk-device-pixel-ratio(3) {
  background-image: govuk-image-url("my-image-3x.png");
}

View source code for _device-pixels.scss on GitHub

Accessibility

govuk-focused-text

Focused text

Provides an outline to clearly indicate when the target element is focused. Used for interactive text-based elements.

Usage
@include govuk-focused-text;

.govuk-link:focus {
  @include govuk-focused-text;
}

View source code for _focused.scss on GitHub

govuk-focused-box

Focused box

Provides an outline to clearly indicate when the target element is focused. Unlike govuk-focused-text, which only draws an underline below the element, govuk-focused-box draws an outline around all sides of the element. Best used for non-text content contained within links.

Usage
@include govuk-focused-box;
Example: Styling the focus state for a linked image
.govuk-link-image:focus {
  @include govuk-focused-box;
}

View source code for _focused.scss on GitHub

govuk-focused-form-input

Focused form input

Provides an outline to clearly indicate when the target element is focused. Used for form inputs.

Usage
@include govuk-focused-form-input;
Example: Styling the focus state for a form input
.govuk-input:focus {
  @include govuk-focused-form-input;
}

View source code for _focused.scss on GitHub

govuk-visually-hidden

Hide an element visually, but have it available for screen readers

Parameters
Name Description Type Default value
$important Whether to mark as !important Boolean true
Usage
@include govuk-visually-hidden($important: true);

View source code for _visually-hidden.scss on GitHub

govuk-visually-hidden-focusable

Hide an element visually, but have it available for screen readers whilst allowing the element to be focused when navigated to via the keyboard (e.g. for the skip link)

Parameters
Name Description Type Default value
$important Whether to mark as !important Boolean true
Usage
@include govuk-visually-hidden-focusable($important: true);

View source code for _visually-hidden.scss on GitHub

Colour

govuk-colour

Get a colour from the palette

Before using this function, check if your use case is covered by a functional colour. For example, use govuk-functional-colour("link") for links rather than govuk-colour("blue").

Parameters
Name Description Type Default value
$colour Name of colour from the colour palette ($_govuk-palette) String or Colour
$variant Name of the variant from the colour palette ($_govuk-palette) String or Colour
Example: Getting the primary variant of a colour
.my-component {
  color: govuk-colour("blue");
}
Example: Getting a 50% shade of blue
.my-component {
  color: govuk-colour("blue", $variant: "shade-50")
}

View source code for _colour.scss on GitHub

govuk-functional-colour

Get a functional colour

Parameters
Name Description Type Default value
$colour Name of the colour from the list of functional colours `String Colour`
Example: Getting a functional colour
.branded-element {
  color: govuk-functional-colour('brand');
}
Example: Output from getting a functional colour
.branded-element {
  /* Assuming the 'brand' colour is hotpink */
  color: var(--govuk-brand-colour, hotpink);
}

View source code for _colour.scss on GitHub

govuk-organisation-colour

Get the colour for a government organisation

Parameters
Name Description Type Default value
$organisation Organisation name, lowercase, hyphenated String
$contrast-safe By default a version of the colour will be returned which has a minimum 4.5:1 contrast ratio when used with white, as per the WCAG 2.1 Level AA guidelines. If you want to use the non-contrast safe version you can set this to false but your should ensure that you still meets contrast requirements for accessibility - for example, do not use the non-contrast safe version for text. Boolean true

View source code for _colour.scss on GitHub

Layout

govuk-clearfix

Clear floated content within a container using a pseudo element

Usage
@include govuk-clearfix;

View source code for _clearfix.scss on GitHub

govuk-grid-width

Grid width percentage

Parameters
Name Description Type Default value
$key Name of grid width (e.g. two-thirds) String

View source code for _grid.scss on GitHub

govuk-grid-column

Generate grid column styles

Creates a grid column with standard gutter between the columns.

Grid widths are defined in the $govuk-grid-widths map.

By default the column width changes from 100% to specified width at the ‘tablet’ breakpoint, but other breakpoints can be specified using the $at parameter.

Parameters
Name Description Type Default value
$width name of a grid width from $govuk-grid-widths String full
$float left | right String left
$at mobile | tablet | desktop | any custom breakpoint String tablet
Usage
@include govuk-grid-column($width: "full", $float: "left", $at: "tablet");
Example: Default
.govuk-grid-column-two-thirds {
  @include govuk-grid-column(two-thirds)
}
Example: Customising the breakpoint where width percentage is applied
.govuk-grid-column-one-half-from-desktop {
  @include govuk-grid-column(one-half, $at: desktop);
}
Example: Customising the float direction
.govuk-grid-column-one-half-right {
  @include govuk-grid-column(two-thirds, $float: right);
}

View source code for _grid.scss on GitHub

govuk-breakpoint-value

Get the value of a breakpoint by name.

Parameters
Name Description Type Default value
$value If a string, the name of a breakpoint in $breakpoints. If a number without units, it will convert to px. If a number with units, it will return the value unaltered. String or Number
$breakpoints The map to look for $value. Map $govuk-breakpoints
Example
.element {
  width: govuk-breakpoint-value(tablet);
  @media (min-width: #{govuk-breakpoint-value(desktop)}) {
    color: red;
  }
  @media (min-width: #{govuk-breakpoint-value(400px)}) {
    color: green;
  }
  $custom-breakpoint-map: (
    small: 350px,
    medium: 769px,
    large: 1100px,
    extra-large: 1600px
  );
  @media (orientation: landscape) and (min-width: #{govuk-breakpoint-value(extra-large, $custom-breakpoint-map)}) {
    color: blue;
  }
}

View source code for _media-queries.scss on GitHub

govuk-from-breakpoint

Generate the min-width segment of a media query given a breakpoint key

Pixel values are converted to ems for backwards compatibility with sass-mq. Unlike sass-mq, non-px and em values can be used as well.

Parameters
Name Description Type Default value
$from If a string, expects the name of a breakpoint in $breakpoints. If a number, it will use that number. String or Number
$breakpoints The map to look for $from. Map $govuk-breakpoints
Example
.example {
  @media #{govuk-from-breakpoint(tablet)} {
    color: red;
  }
  @media #{govuk-from-breakpoint(30em)} {
    color: green;
  }
  @media #{govuk-from-breakpoint(tablet)} and (orientation: landscape) {
    color: blue;
  }
  $custom-breakpoint-map: (
    small: 350px,
    medium: 769px,
    large: 1100px,
    extra-large: 1600px
  );
  @media #{govuk-from-breakpoint(extra-large, $custom-breakpoint-map)} {
    color: cyan;
  }
}

View source code for _media-queries.scss on GitHub

govuk-until-breakpoint

Generate the max-width segment of a media query given a breakpoint key

sass-mq converted pixel values to ems, and only performed subtractions on named breakpoints. These have been retained for backwards compatibility, though unlike sass-mq, this also supports using non-px and em values.

Parameters
Name Description Type Default value
$until If a string, expects the name of a breakpoint in $breakpoints. If a number, it will use that number. String or Number
$breakpoints The map to look for $until. Map $govuk-breakpoints
Example
.example {
  @media #{govuk-until-breakpoint(desktop)} {
    color: red;
  }
  @media #{govuk-until-breakpoint(40em)} {
    color: green;
  }
  @media #{govuk-until-breakpoint(tablet)} and (orientation: landscape) {
    color: blue;
  }
  $custom-breakpoint-map: (
    small: 350px,
    medium: 769px,
    large: 1100px,
    extra-large: 1600px
  );
  @media #{govuk-until-breakpoint(extra-large, $custom-breakpoint-map)} {
    color: cyan;
  }
}

View source code for _media-queries.scss on GitHub

govuk-media-query

Media query

Parameters
Name Description Type Default value
$from One of $breakpoints String or Boolean false
$until One of $breakpoints String or Boolean false
$and Additional media query parameters String or Boolean false
$media-type Override media type: screen, print… String all
$breakpoints Map of breakpoints to use Map $govuk-breakpoints
Usage
@include govuk-media-query($from: false, $until: false, $and: false, $media-type: "all", $breakpoints: $govuk-breakpoints) {
  //..
}
Example
.element {
  @include govuk-media-query($from: mobile) {
    color: red;
  }
  @include govuk-media-query($until: tablet) {
    color: blue;
  }
  @include govuk-media-query(mobile, tablet) {
    color: green;
  }
  @include govuk-media-query($from: tablet, $and: '(orientation: landscape)') {
    color: teal;
  }
  @include govuk-media-query(950px) {
    color: hotpink;
  }
  @include govuk-media-query(tablet, $media-type: screen) {
    color: rebeccapurple;
  }
}

View source code for _media-queries.scss on GitHub

Common link styles

Provides the typography and focus state, regardless of link style.

@include govuk-link-common;

View source code for _links.scss on GitHub

Link decoration

Provides the text decoration for links, including thickness and underline offset. Use this mixin only if you cannot use the govuk-link-common mixin.

@include govuk-link-decoration;

View source code for _links.scss on GitHub

Link hover decoration

Provides the text decoration for links in their hover state, for you to use within a :hover pseudo-selector. Use this mixin only if you cannot use the govuk-link-common mixin.

@include govuk-link-hover-decoration;

View source code for _links.scss on GitHub

Default link styles

Makes links use the default unvisited, visited, hover and active colours.

If you use this mixin in a component, you must also include the govuk-link-common mixin to get the correct focus and hover states.

@include govuk-link-style-default;

.govuk-component__link {
  @include govuk-link-common;
  @include govuk-link-style-default;
}

View source code for _links.scss on GitHub

Error link styles

Makes links use the error colour. The link will darken if it’s active or a user hovers their cursor over it.

If you use this mixin in a component, you must also include the govuk-link-common mixin to get the correct focus and hover states.

@include govuk-link-style-error;

.govuk-component__link {
  @include govuk-link-common;
  @include govuk-link-style-error;
}

View source code for _links.scss on GitHub

Success link styles

Makes links use the success colour. The link will darken if it’s active or a user hovers their cursor over it.

If you use this mixin in a component, you must also include the govuk-link-common mixin to get the correct focus and hover states.

@include govuk-link-style-success;

.govuk-component__link {
  @include govuk-link-common;
  @include govuk-link-style-success;
}

View source code for _links.scss on GitHub

Muted link styles

Makes links use the secondary text colour. The link will darken if it’s active or a user hovers their cursor over it.

If you use this mixin in a component, you must also include the govuk-link-common mixin to get the correct focus and hover states.

@include govuk-link-style-muted;

.govuk-component__link {
  @include govuk-link-common;
  @include govuk-link-style-muted;
}

View source code for _links.scss on GitHub

govuk-link-style-text

Text link styles

Makes links use the primary text colour, in all states. Use this mixin for navigation components, such as breadcrumbs or the back link.

If you use this mixin in a component, you must also include the govuk-link-common mixin to get the correct focus and hover states.

Usage
@include govuk-link-style-text;
Example
.govuk-component__link {
  @include govuk-link-common;
  @include govuk-link-style-text;
}

View source code for _links.scss on GitHub

Inverse link styles

Makes links white, in all states. Use this mixin if you’re displaying links against a dark background.

If you use this mixin in a component, you must also include the govuk-link-common mixin to get the correct focus and hover states.

@include govuk-link-style-inverse;

.govuk-component__link {
  @include govuk-link-common;
  @include govuk-link-style-inverse;
}

View source code for _links.scss on GitHub

Default link styles, without a visited state

Makes links use the default unvisited, hover and active colours, with no distinct visited state.

Use this mixin when it’s not helpful to distinguish between visited and non-visited links. For example, when you link to pages with frequently-changing content, such as the dashboard for an admin interface.

If you use this mixin in a component, you must also include the govuk-link-common mixin to get the correct focus and hover states.

@include govuk-link-style-no-visited-state;

.govuk-component__link {
  @include govuk-link-common;
  @include govuk-link-style-no-visited-state;
}

View source code for _links.scss on GitHub

Remove underline from links

Remove underlines from links unless the link is active or a user hovers their cursor over it.

@include govuk-link-style-no-underline;

.govuk-component__link {
  @include govuk-link-common;
  @include govuk-link-style-default;
  @include govuk-link-style-no-underline;
}

View source code for _links.scss on GitHub

Include link destination when printing the page

If the user prints the page, add the destination URL after the link text, if the URL starts with /, http:// or https://.

@include govuk-link-print-friendly;

View source code for _links.scss on GitHub

Image link styles

Prepares and provides the focus state for links that only contain images with no accompanying text.

@include govuk-link-image;

View source code for _links.scss on GitHub

Shapes

govuk-shape-arrow

Arrow mixin

Generate Arrows (triangles) by using a mix of transparent (1) and coloured borders. The coloured borders inherit the text colour of the element (2).

Ensure the arrow is rendered correctly if browser colours are overridden by providing a clip path (3). Without this the transparent borders are overridden to become visible which results in a square.

We need both because older browsers do not support clip-path.

Parameters
Name Description Type Default value
$direction Direction for arrow: up, right, down, left. String
$base Length of the triangle ‘base’ side Number
$height Height of triangle. Omit for equilateral. Number null
$display CSS display property of the arrow String block
Usage
@include govuk-shape-arrow($direction, $base, $height: null, $display: "block");

View source code for _shape-arrow.scss on GitHub

Spacing

govuk-spacing

Single point spacing

Returns measurement corresponding to the spacing point requested.

Parameters
Name Description Type Default value
$spacing-point Point on the spacing scale (set in settings/_spacing.scss) Number
Example
.element {
  padding: govuk-spacing(5);
}
Example: Using negative spacing
.element {
  margin-top: govuk-spacing(-1);
}
Example: Marking spacing declarations as important
.element {
  margin-top: govuk-spacing(1) !important;
}

View source code for _spacing.scss on GitHub

govuk-responsive-margin

Responsive margin

Adds responsive margin by fetching a ‘spacing map’ from the responsive spacing scale, which defines different spacing values at different breakpoints. Wrapper for the _govuk-responsive-spacing mixin.

Parameters
Name Description Type Default value
$responsive-spacing-point Point on the responsive spacingscale, corresponds to a map of breakpoints and spacing values Number
$direction Direction to add spacing to (top, right, bottom, left, all) String all
$important Whether to mark as !important Boolean false
$adjustment Offset to adjust spacing by Number false
Usage
@include govuk-responsive-margin($responsive-spacing-point, $direction: "all", $important: false, $adjustment: false);
Example
.element {
   @include govuk-responsive-margin(6, "left", $adjustment: 1px);
}

View source code for _spacing.scss on GitHub

govuk-responsive-padding

Responsive padding

Adds responsive padding by fetching a ‘spacing map’ from the responsive spacing scale, which defines different spacing values at different breakpoints. Wrapper for the _govuk-responsive-spacing mixin.

Parameters
Name Description Type Default value
$responsive-spacing-point Point on the responsive spacing scale, corresponds to a map of breakpoints and spacing values Number
$direction Direction to add spacing to (top, right, bottom, left, all) String all
$important Whether to mark as !important Boolean false
$adjustment Offset to adjust spacing Number false
Usage
@include govuk-responsive-padding($responsive-spacing-point, $direction: "all", $important: false, $adjustment: false);
Example
.element {
   @include govuk-responsive-padding(6, "left", $adjustment: 1px);
}

View source code for _spacing.scss on GitHub

Typography

govuk-typography-common

‘Common typography’ helper

Sets the font family and associated properties, such as font smoothing. Also overrides the font for print.

Parameters
Name Description Type Default value
$font-family Font family to use List $govuk-font-family
Usage
@include govuk-typography-common($font-family: $govuk-font-family);

View source code for _typography.scss on GitHub

govuk-text-colour

Text colour helper

Sets the text colour, including a suitable override for print.

Usage
@include govuk-text-colour;

View source code for _typography.scss on GitHub

govuk-typography-weight-regular

Regular font weight helper

Parameters
Name Description Type Default value
$important Whether to mark declarations as !important. Generally Used to create override classes. Boolean false
Usage
@include govuk-typography-weight-regular($important: false);

View source code for _typography.scss on GitHub

govuk-typography-weight-bold

Bold font weight helper

Parameters
Name Description Type Default value
$important Whether to mark declarations as !important. Generally Used to create override classes. Boolean false
Usage
@include govuk-typography-weight-bold($important: false);

View source code for _typography.scss on GitHub

govuk-font-tabular-numbers

Tabular number helper

Switches numerical glyphs (0–9) to use alternative forms with a monospaced bounding box. This ensures that columns of numbers, such as those in tables, remain horizontally aligned with one another. This also has the useful side effect of making numbers more legible in some situations, such as reference codes, as the numbers are more distinct and visually separated from one another.

Parameters
Name Description Type Default value
$important Whether to mark declarations as !important. Generally Used to create override classes. Boolean false
Usage
@include govuk-font-tabular-numbers($important: false);

View source code for _typography.scss on GitHub

govuk-text-break-word

Word break helper

Forcibly breaks long words that lack spaces, such as email addresses, across multiple lines when they wouldn’t otherwise fit.

Parameters
Name Description Type Default value
$important Whether to mark declarations as !important. Generally used to create override classes. Boolean false
Usage
@include govuk-text-break-word($important: false);

View source code for _typography.scss on GitHub

govuk-font-size

Font size and line height helper

Takes a point from the responsive ‘font map’ as an argument (the size as it would appear on tablet and above), and uses it to create font-size and line-height declarations for different breakpoints, and print.

Example font map:

19: (
  null: (
    font-size: 16px,
    line-height: 20px
  ),
  tablet: (
    font-size: 19px,
    line-height: 25px
  ),
  print: (
    font-size: 14pt,
    line-height: 1.15
  )
);
Parameters
Name Description Type Default value
$size Point from the type scale (the size as it would appear on tablet and above) Number or String
$line-height Non responsive custom line height. Omit to use the line height from the font map. Number false
$important Whether to mark declarations as !important. Boolean false
Usage
@include govuk-font-size($size, $line-height: false, $important: false);

View source code for _typography.scss on GitHub

govuk-font

Font helper

Parameters
Name Description Type Default value
$size Point from the type scale (the size as it would appear on tablet and above). Use false to avoid setting a size. Number or Boolean or String
$weight Weight: bold or regular String regular
$tabular Whether to use tabular numbers or not Boolean false
$line-height Line-height, if overriding the default Number false
Usage
@include govuk-font($size, $weight: "regular", $tabular: false, $line-height: false);

View source code for _typography.scss on GitHub

Components

Button

$govuk-button-background-colour

Button component background colour

Default value
$govuk-button-background-colour: govuk-colour("green");

View source code for _index.scss on GitHub

$govuk-button-text-colour

Button component text colour

Default value
$govuk-button-text-colour: govuk-colour("white");

View source code for _index.scss on GitHub

$govuk-inverse-button-background-colour

Inverted button component background colour

Default value
$govuk-inverse-button-background-colour: govuk-colour("white");

View source code for _index.scss on GitHub

$govuk-inverse-button-text-colour

Inverted button component text colour

Default value
$govuk-inverse-button-text-colour: govuk-functional-colour(brand);

View source code for _index.scss on GitHub

Objects

Layout

govuk-width-container

Width container mixin

Used to create page width and custom width container classes.

Parameters
Name Description Type Default value
$width Width in pixels String $govuk-page-width
Usage
@include govuk-width-container($width: "$govuk-page-width");
Example: Creating a 1200px wide container class
.app-width-container--wide {
  @include govuk-width-container(1200px);
}

View source code for _width-container.scss on GitHub