Helpers

mixins

govuk-clearfix

@mixin govuk-clearfix() { ... }

Description

Clear floated content within a container using a pseudo element

Parameters

None.

govuk-device-pixel-ratio

@mixin govuk-device-pixel-ratio($ratio: 2) { ... }

Description

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

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$ratio

Device pixel ratio

Number2

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");
}

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");
}

govuk-focused-text

@mixin govuk-focused-text() { ... }

Description

Focused text

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

Parameters

None.

Requires

Used by

[private] _govuk-font-face-gds-transport

@mixin _govuk-font-face-gds-transport() { ... }

Description

Font Face - GDS Transport

Outputs the font-face declaration for GDS Transport at the root of the CSS document the first time it is called.

Parameters

None.

Requires

Used by

govuk-grid-column

@mixin govuk-grid-column($width: full, $float: left, $at: tablet) { ... }

Description

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

parameter Nameparameter Descriptionparameter Typeparameter Default value
$width

name of a grid width from $govuk-grid-widths

Stringfull
$float

left | right

Stringleft
$at

mobile | tablet | desktop | any custom breakpoint

Stringtablet

Example

Default

.govuk-grid-column-two-thirds {
  @include govuk-grid-column(two-thirds)
}

Customising the breakpoint where width percentage is applied

.govuk-grid-column-one-half-at-desktop {
  @include govuk-grid-column(one-half, $at: desktop);
}

Customising the float direction

.govuk-grid-column-one-half-right {
  @include govuk-grid-column(two-thirds, $float: right);

Requires

govuk-media-query

@mixin govuk-media-query($from: false, $until: false, $and: false, $media-type: all) { ... }

Description

Media Query

This is a currently a wrapper for sass-mq - abstracted so that we can replace it in the future if we so choose.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$from

One of $govuk-breakpoints

String or Booleanfalse
$until

One of $govuk-breakpoints

String or Booleanfalse
$and

Additional media query parameters

String or Booleanfalse
$media-type

Media type: screen, print…

Stringall

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: hotpink;
  }
}

Used by

govuk-shape-arrow

@mixin govuk-shape-arrow($direction, $base, $height: null, $display: block) { ... }

Description

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

parameter Nameparameter Descriptionparameter Typeparameter Default value
$direction

Direction for arrow: up, right, down, left.

String none
$base

Length of the triangle 'base' side

Number none
$height

Height of triangle. Omit for equilateral.

Numbernull
$display

CSS display property of the arrow

Stringblock

Throws

  • Invalid arrow direction: expected up, right, down or left, got #{$direction}

Requires

[private] _govuk-responsive-spacing

@mixin _govuk-responsive-spacing($responsive-spacing-point, $property, $direction: all, $important: false, $adjustment: false) { ... }

Description

Responsive spacing

Adds responsive spacing (either padding or margin, depending on $property) by fetching a 'spacing map' from the responsive spacing scale, which defines different spacing values at different breakpoints.

To generate responsive spacing, use 'govuk-responsive-margin' or 'govuk-responsive-padding' mixins

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$responsive-spacing-point

Point on the responsive spacing scale, corresponds to a map of breakpoints and spacing values

Number none
$property

Property to add spacing to (e.g. 'margin')

String none
$direction

Direction to add spacing to (top, right, bottom, left, all)

Stringall
$important

Whether to mark as !important

Booleanfalse
$adjustment

Offset to adjust spacing by

Numberfalse

Throws

  • Expected a number (integer), but got a

  • Unknown spacing point #{$responsive-spacing-point}. Make sure you are using a point from the

Requires

Used by

govuk-responsive-margin

@mixin govuk-responsive-margin($responsive-spacing-point, $direction: all, $important: false, $adjustment: false) { ... }

Description

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

parameter Nameparameter Descriptionparameter Typeparameter Default value
$responsive-spacing-point

Point on the responsive spacing scale, corresponds to a map of breakpoints and spacing values

Number none
$direction

Direction to add spacing to (top, right, bottom, left, all)

Stringall
$important

Whether to mark as !important

Booleanfalse
$adjustment

Offset to adjust spacing by

Numberfalse

Example

.element {
   @include govuk-responsive-margin(6, "left", $adjustment: 1px);
}

Requires

See

govuk-responsive-padding

@mixin govuk-responsive-padding($responsive-spacing-point, $direction: all, $important: false, $adjustment: false) { ... }

Description

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

parameter Nameparameter Descriptionparameter Typeparameter Default value
$responsive-spacing-point

Point on the responsive spacing scale, corresponds to a map of breakpoints and spacing values

Number none
$direction

Direction to add spacing to (top, right, bottom, left, all)

Stringall
$important

Whether to mark as !important

Booleanfalse
$adjustment

Offset to adjust spacing

Numberfalse

Example

.element {
   @include govuk-responsive-padding(6, "left", $adjustment: 1px);
}

Requires

Used by

See

govuk-typography-common

@mixin govuk-typography-common($font-family: $govuk-font-family) { ... }

Description

'Common typography' helper

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

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$font-family

Font family to use

List$govuk-font-family

Requires

Used by

govuk-text-colour

@mixin govuk-text-colour() { ... }

Description

Text colour helper

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

Parameters

None.

Requires

Used by

govuk-typography-weight-regular

@mixin govuk-typography-weight-regular($important: false) { ... }

Description

Regular font weight helper

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$important

Whether to mark declarations as !important. Generally Used to create override classes.

Booleanfalse

Requires

Used by

govuk-typography-weight-bold

@mixin govuk-typography-weight-bold($important: false) { ... }

Description

Bold font weight helper

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$important

Whether to mark declarations as !important. Generally Used to create override classes.

Booleanfalse

Requires

Used by

govuk-typography-responsive

@mixin govuk-typography-responsive($font-map, $override-line-height: false, $important: false) { ... }

Description

Responsive typography helper

Takes a 'font map' as an argument and uses it to create font-size and line-height declarations for different breakpoints, and for print.

Example font map:

$my-font-map: ( null: ( font-size: 16px, line-height: 20px ), tablet: ( font-size: 19px, line-height: 25px ), print: ( font-size: 14pt, line-height: 1.15 ) );

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$font-map

Font map

Map none
$override-line-height

Non responsive custom line height. Omit to use the line height from the font map.

Numberfalse
$important

Whether to mark declarations as !important.

Booleanfalse

Throws

  • Unknown font size #{$size} - expected a point from the typography scale.

Requires

Used by

govuk-font

@mixin govuk-font($size, $weight: regular, $tabular: false, $line-height: false) { ... }

Description

Font helper

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$size

Size of the font as it would appear on desktop - uses the responsive font size map

Number none
$weight

Weight: bold or regular

Stringregular
$tabular

Whether to use tabular numbers or not

Booleanfalse
$line-height

Line-height, if overriding the default

Numberfalse

Requires

govuk-visually-hidden

@mixin govuk-visually-hidden($important: true) { ... }

Description

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

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$important

Whether to mark as !important

Booleantrue

Requires

Links

govuk-visually-hidden-focusable

@mixin govuk-visually-hidden-focusable($important: true) { ... }

Description

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)

This is slightly less opinionated about borders and padding to make it easier to style the focussed element.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$important

Whether to mark as !important

Booleantrue

Requires

functions

govuk-grid-width

@function govuk-grid-width($key) { ... }

Description

Grid width percentage

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$key

Name of grid width (e.g. two-thirds)

String none

Returns

Number

Percentage width

Throws

  • Unknown grid width #{$key}

Requires

Used by

[private] _govuk-equilateral-height

@function _govuk-equilateral-height($base) { ... }

Description

Calculate the height of an equilateral triangle

Multiplying half the length of the base of an equilateral triangle by the square root of three gives us its height. We use 1.732 as an approximation.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$base

Length of the base of the triangle

Number none

Returns

Number

Calculated height of the triangle

Used by

govuk-spacing

@function govuk-spacing($spacing-point) { ... }

Description

Single point spacing

Returns measurement corresponding to the spacing point requested.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$spacing-point

Point on the spacing scale (set in settings/_spacing.sccs)

Number none

Returns

String

Spacing Measurement eg. 10px

Example

.element {
  padding: govuk-spacing(5);
  top: govuk-spacing(2) !important; // if `!important` is required
}

Throws

  • Expected a number (integer), but got a

  • Unknown spacing variable #{$spacing-point}. Make sure you are using a point from the spacing scale in _settings/spacing.scss.

Requires

Used by

[private] _govuk-line-height

@function _govuk-line-height($line-height, $font-size) { ... }

Description

Convert line-heights specified in pixels into a relative value, unless they are already unit-less (and thus already treated as relative values) or the units do not match the units used for the font size.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$line-height

Line height

Number none
$font-size

Font size

Number none

Returns

Number

The line height as either a relative value or unmodified

Used by

helpers/colour

functions

govuk-colour

@function govuk-colour($colour, $legacy) { ... }

Description

Get colour

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$colour

Name of colour from the colour palette ($govuk-colours)

String none
$legacy

Either the name of colour from the legacy palette or a colour literal, to return instead when in 'legacy mode' - matching the palette from GOV.UK Template, Elements or Frontend Toolkit

String none

Returns

Colour

Representation of named colour

Example

Using legacy colours from the palette

.foo {
  background-colour: govuk-colour("mid-grey", $legacy: "grey-2");
}

Using legacy colour literals

.foo {
  background-colour: govuk-colour("green", $legacy: #BADA55);
}

Throws

  • Unknown colour #{$colour}

Requires

Used by

govuk-organisation-colour

@function govuk-organisation-colour($organisation, $websafe: true) { ... }

Description

Get the colour for a government organisation

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$organisation

Organisation name, lowercase, hyphenated

String none
$websafe

By default a 'websafe' version of the colour will be returned which meets contrast requirements . If you want to use the non-websafe version you can set this to false but your should ensure that you still meets contrast requirements for accessibility - for example, don't use the non-websafe version for text.

Booleantrue

Returns

Colour

Representation of colour for organisation

Throws

  • Unknown organisation #{$organisation}

Requires

govuk-shade

@function govuk-shade($colour, $percentage) { ... }

Description

Make a colour darker by mixing it with black

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$colour

colour to shade

Colour none
$percentage

percentage of $colour in returned color

Number none

Returns

Colour

govuk-tint

@function govuk-tint($colour, $percentage) { ... }

Description

Make a colour lighter by mixing it with white

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$colour

colour to tint

Colour none
$percentage

percentage of $colour in returned color

Number none

Returns

Colour

Requires

Overrides

variables

[private] _spacing-directions

$_spacing-directions: (
  "top",
  "right",
  "bottom",
  "left"
) !default;

Description

Directions for spacing

Type

Map

Used by

mixins

[private] _govuk-generate-spacing-overrides

@mixin _govuk-generate-spacing-overrides($property) { ... }

Description

Spacing override classes

Generate spacing override classes for the given property (e.g. margin) for each point in the spacing scale.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$property

Property to add spacing to (e.g. 'margin')

String none

Example

 .govuk-\!-margin-0 {
    margin: 0;
 }

.govuk-\!-margin-top-1 {
   margin-top: [whatever spacing point 1 is...]
 }

Requires

Settings / Assets

variables

govuk-assets-path

$govuk-assets-path: "/assets/" !default;

Description

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.

Type

String

govuk-images-path

$govuk-images-path: "#{$govuk-assets-path}images/" !default;

Description

Path to the images folder, with trailing slash.

Type

String

Used by

govuk-fonts-path

$govuk-fonts-path: "#{$govuk-assets-path}fonts/" !default;

Description

Path to the fonts folder, with trailing slash.

Type

String

Used by

govuk-image-url-function

$govuk-image-url-function: false !default;

Description

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()

Type

String

Example

Rails asset handling

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

Custom asset handling

@function my-url-handler($filename) {
  // Some custom URL handling
  @return url('example.jpg');
}

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

Used by

govuk-font-url-function

$govuk-font-url-function: false !default;

Description

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()

Type

String

Example

Rails asset handling

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

Custom asset handling

@function my-url-handler($filename) {
  // Some custom URL handling
  @return url('example.woff');
}

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

Used by

Settings / Colours

variables

govuk-brand-colour

$govuk-brand-colour: govuk-colour("blue") !default;

Description

Brand colour

Type

Colour

govuk-text-colour

$govuk-text-colour: govuk-colour("black") !default;

Description

Text colour

Type

Colour

Used by

govuk-canvas-background-colour

$govuk-canvas-background-colour: govuk-colour("light-grey", $legacy: "grey-3") !default;

Description

Canvas background colour

Used by the footer component and template to give the illusion of a long footer.

Type

Colour

govuk-body-background-colour

$govuk-body-background-colour: govuk-colour("white") !default;

Description

Body background colour

Type

Colour

govuk-print-text-colour

$govuk-print-text-colour: #000000 !default;

Description

Text colour for print media

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

Type

Colour

Used by

govuk-secondary-text-colour

$govuk-secondary-text-colour: govuk-colour("dark-grey", $legacy: "grey-1") !default;

Description

Secondary text colour

Used for 'muted' text, help text, etc.

Type

Colour

Used by

govuk-focus-colour

$govuk-focus-colour: govuk-colour("yellow") !default;

Description

Focus colour

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

Type

Colour

Used by

govuk-focus-text-colour

$govuk-focus-text-colour: govuk-colour("black") !default;

Description

Focused text colour

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

Type

Colour

Used by

govuk-error-colour

$govuk-error-colour: govuk-colour("red") !default;

Description

Error colour

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

Type

Colour

govuk-border-colour

$govuk-border-colour: govuk-colour("mid-grey", $legacy: "grey-2");

Description

Border colour

Used for borders, separators, rules, keylines etc.

Type

Colour

govuk-input-border-colour

$govuk-input-border-colour: govuk-colour("black") !default;

Description

Input border colour

Used for form inputs and controls

Type

Colour

govuk-hover-colour

$govuk-hover-colour: govuk-colour("mid-grey", $legacy: "grey-3");

Description

Input hover colour

Used for hover states on form controls

Type

Colour

govuk-colours-organisations

$govuk-colours-organisations: (
  "attorney-generals-office": (
    colour: #9f1888,
    colour-websafe: #a03a88
  ),
  "cabinet-office": (
    colour: #005abb,
    colour-websafe: #347da4
  ),
  "civil-service": (
    colour: #af292e
  ),
  "department-for-business-innovation-skills": (
    colour: #003479,
    colour-websafe: #347da4
  ),
  "department-for-communities-and-local-government": (
    colour: #009999,
    colour-websafe: #37836e
  ),
  "department-for-culture-media-sport": (
    colour: #d40072,
    colour-websafe: #a03155
  ),
  "department-for-education": (
    colour: #003a69,
    colour-websafe: #347ca9
  ),
  "department-for-environment-food-rural-affairs": (
    colour: #00a33b,
    colour-websafe: #008938
  ),
  "department-for-international-development": (
    colour: #002878,
    colour-websafe: #405e9a
  ),
  "department-for-international-trade": (
    colour: #cf102d,
    colour-websafe: #005ea5
  ),
  "department-for-transport": (
    colour: #006c56,
    colour-websafe: #398373
  ),
  "department-for-work-pensions": (
    colour: #00beb7,
    colour-websafe: #37807b
  ),
  "department-of-energy-climate-change": (
    colour: #009ddb,
    colour-websafe: #2b7cac
  ),
  "department-of-health": (
    colour: #00ad93,
    colour-websafe: #39836e
  ),
  "foreign-commonwealth-office": (
    colour: #003e74,
    colour-websafe: #406e97
  ),
  "government-equalities-office": (
    colour:  #9325b2
  ),
  "hm-government": (
    colour: #0076c0,
    colour-websafe: #347da4
  ),
  "hm-revenue-customs": (
    colour: #009390,
    colour-websafe: #008670
  ),
  "hm-treasury": (
    colour: #af292e,
    colour-websafe: #832322
  ),
  "home-office": (
    colour: #9325b2,
    colour-websafe: #9440b2
  ),
  "ministry-of-defence": (
    colour: #4d2942,
    colour-websafe: #5a5c92
  ),
  "ministry-of-justice": (
    colour: #231f20,
    colour-websafe: #5a5c92
  ),
  "northern-ireland-office": (
    colour: #002663,
    colour-websafe: #3e598c
  ),
  "office-of-the-advocate-general-for-scotland": (
    colour: #002663,
    colour-websafe: #005ea5
  ),
  "office-of-the-leader-of-the-house-of-commons": (
    colour: #317023,
    colour-websafe: #005f8f
  ),
  "office-of-the-leader-of-the-house-of-lords": (
    colour: #9c132e,
    colour-websafe: #c2395d
  ),
  "scotland-office": (
    colour: #002663,
    colour-websafe: #405c8a
  ),
  "uk-export-finance": (
    colour: #005747,
    colour-websafe: #005ea5
  ),
  "uk-trade-investment": (
    colour: #c80651,
    colour-websafe: #005ea5
  ),
  "wales-office": (
    colour: #a33038,
    colour-websafe: #7a242a
  )
) !default;

Description

Organisation colours

Type

Map

Map structure

Map key NameMap key DescriptionMap key TypeMap key Value
$organisation.colour

Colour for the given $organisation

Map none
$organisation.colour-websafe

Websafe colour for the given $organisation. We use websafe to mean strong enough contrast against white to be used for copy and meet the AAA (large text) and AA (smaller copy) WCAG guidelines.

Map none

Used by

govuk-use-legacy-palette

$govuk-use-legacy-palette: if((
    $govuk-compatibility-govukfrontendtoolkit or
    $govuk-compatibility-govuktemplate or
    $govuk-compatibility-govukelements
  ), true, false) !default;

Description

Use 'legacy' colour palette

Whether or not to use the colour palette from GOV.UK Elements / Frontend Toolkit, for teams that are migrating to GOV.UK Frontend and may be using components from both places in a single application.

Type

Boolean

Used by

[private] _govuk-colour-palette-legacy

$_govuk-colour-palette-legacy: (
  "purple": #2e358b,
  "light-purple": #6f72af,
  "bright-purple": #912b88,
  "pink": #d53880,
  "light-pink": #f499be,
  "red": #b10e1e,
  "bright-red": #df3034,
  "orange": #f47738,
  "brown": #b58840,
  "yellow": #ffbf47,
  "light-green": #85994b,
  "green": #006435,
  "turquoise": #28a197,
  "light-blue": #2b8cc4,
  "blue": #005ea5,

  "black": #0b0c0c,
  "grey-1": #6f777b,
  "grey-2": #bfc1c3,
  "grey-3": #dee0e2,
  "grey-4": #f8f8f8,
  "white": #ffffff
);

Description

Legacy colour palette

This exists only because you cannot easily set a !default variable conditionally (thanks to the way scope works in Sass) so we set $govuk-colour-palette using the if function.

[private] _govuk-colour-palette-modern

$_govuk-colour-palette-modern: (
  "red": #d4351c,
  "yellow": #ffdd00,
  "green": #00703c,
  "blue": #1d70b8,
  "dark-blue": #003078,
  "light-blue": #5694ca,
  "purple": #4c2c92,

  "black": #0b0c0c,
  "dark-grey": #6f777b,
  "mid-grey": #b1b4b6,
  "light-grey": #f3f2f1,
  "white": #ffffff,

  "light-purple": #6f72af,
  "bright-purple": #912b88,
  "pink": #d53880,
  "light-pink": #f499be,
  "orange": #f47738,
  "brown": #b58840,
  "light-green": #85994b,
  "turquoise": #28a197
);

Description

Modern colour palette

This exists only because you cannot easily set a !default variable conditionally (thanks to the way scope works in Sass) so we set $govuk-colour-palette using the if function.

govuk-colours

$govuk-colours: if(
  $govuk-use-legacy-palette,
  $_govuk-colour-palette-legacy,
  $_govuk-colour-palette-modern
) !default;

Description

Colour palette

Type

Map

Map structure

Map key NameMap key DescriptionMap key TypeMap key Value
$colour

Representation for the given $colour, where $colour is the friendly name for the colour (e.g. "red": #ff0000);

Map none

Used by

Settings / Compatibility

variables

govuk-compatibility-govukfrontendtoolkit

$govuk-compatibility-govukfrontendtoolkit: false !default;

Description

Compatibility Mode: alphagov/govuk_frontend_toolkit

Set this to true if you are also including alphagov/govuk_frontend_toolkit in your application.

Type

Boolean

govuk-compatibility-govuktemplate

$govuk-compatibility-govuktemplate: false !default;

Description

Compatibility Mode: alphagov/govuk_template

Enabling this will:

  • prevent GOV.UK Frontend from including the New Transport typeface, as it'll use the version of New Transport included with GOV.UK Template.

  • alter some of the CSS outputted by GOV.UK Frontend to 'counter' specific CSS rules in GOV.UK Template.

Set this to true if you are also including alphagov/govuk_template in your application.

Type

Boolean

govuk-compatibility-govukelements

$govuk-compatibility-govukelements: false !default;

Description

Compatibility Mode: alphagov/govuk_elements

Enabling this will:

  • alter some of the CSS outputted by GOV.UK Frontend to 'counter' specific CSS rules in GOV.UK Elements.

Set this to true if you are also including alphagov/govuk_elements in your application.

Type

Boolean

[private] _govuk-compatibility

$_govuk-compatibility: (
  govuk_frontend_toolkit: $govuk-compatibility-govukfrontendtoolkit,
  govuk_template: $govuk-compatibility-govuktemplate,
  govuk_elements: $govuk-compatibility-govukelements,
);

Description

Compatibility Product Map

Maps product names to their settings that we can use to lookup states from within the @govuk-compatibility mixin.

Type

Map

Used by

Settings / Global Styles

variables

govuk-global-styles

$govuk-global-styles: false !default;

Description

Include 'global' styles

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

Type

Boolean

Settings / IE8

variables

govuk-is-ie8

$govuk-is-ie8: false !default;

Description

Whether the stylesheet being built is targeting Internet Explorer 8.

Type

Boolean

Used by

govuk-ie8-breakpoint

$govuk-ie8-breakpoint: desktop !default;

Description

The name of the breakpoint to use as the target when rasterizing media queries

Type

String

Settings / Measurements

variables

govuk-page-width

$govuk-page-width: 960px !default;

Description

Width of main container

Type

Number

govuk-grid-widths

$govuk-grid-widths: (
  one-quarter: 25%,
  one-third: 33.3333%,
  one-half: 50%,
  two-thirds: 66.6666%,
  three-quarters: 75%,
  full: 100%
) !default;

Description

Map of grid column widths

Type

Map

Used by

govuk-gutter

$govuk-gutter: 30px !default;

Description

Width of gutter between grid columns

Type

Number

govuk-gutter-half

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

Description

Width of half the gutter between grid columns

Type

Number

Used by

govuk-border-width

$govuk-border-width: 5px !default;

Description

Standard border width

Type

Number

govuk-border-width-wide

$govuk-border-width-wide: 10px !default;

Description

Wide border width

Type

Number

govuk-border-width-narrow

$govuk-border-width-narrow: 4px !default;

Description

Narrow border width

Type

Number

govuk-border-width-form-element

$govuk-border-width-form-element: 2px !default;

Description

Form control border width

Type

Number

govuk-border-width-form-element-error

$govuk-border-width-form-element-error: 4px !default;

Description

Form control border width when in error state

Type

Number

govuk-border-width-form-group-error

$govuk-border-width-form-group-error: $govuk-border-width !default;

Description

Form group border width when in error state

Type

Number

govuk-focus-width

$govuk-focus-width: 3px !default;

Description

Border width of focus outline

Type

Number

Used by

govuk-hover-width

$govuk-hover-width: 10px !default;

Description

Hover width for form controls with a hover state

Type

Number

Settings / Media Queries

variables

govuk-breakpoints

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

Description

Breakpoint definitions

Type

Map

govuk-show-breakpoints

$govuk-show-breakpoints: false !default;

Description

Show active breakpoint in top-right corner.

Only use this during local development.

Type

Boolean

Settings / Spacing

variables

[private] govuk-spacing-points

$govuk-spacing-points: (
  0: 0,
  1: 5px,
  2: 10px,
  3: 15px,
  4: 20px,
  5: 25px,
  6: 30px,
  7: 40px,
  8: 50px,
  9: 60px
) !default;

Description

Single point spacing variables. Access using govuk-spacing() (see helpers/spacing).

Type

Map

Used by

[private] govuk-spacing-responsive-scale

$govuk-spacing-responsive-scale: (
  0: (
    null: 0,
    tablet: 0
  ),
  1: (
    null: 5px,
    tablet: 5px
  ),
  2: (
    null: 10px,
    tablet: 10px
  ),
  3: (
    null: 15px,
    tablet: 15px
  ),
  4: (
    null: 15px,
    tablet: 20px
  ),
  5: (
    null: 15px,
    tablet: 25px
  ),
  6: (
    null: 20px,
    tablet: 30px
  ),
  7: (
    null: 25px,
    tablet: 40px
  ),
  8: (
    null: 30px,
    tablet: 50px
  ),
  9: (
    null: 40px,
    tablet: 60px
  )
) !default;

Description

Responsive spacing maps

These definitions are used to generate responsive spacing that adapts according to the breakpoints (see 'helpers/spacing'). These maps should be used wherever possible to standardise responsive spacing.

You can define different behaviour on tablet and desktop. The 'null' breakpoint is for mobile.

Access responsive spacing with govuk-responsive-margin or govuk-responsive-padding mixins (see helpers/spacing).

Type

Map

Used by

Settings / Typography

variables

govuk-font-family-gds-transport

$govuk-font-family-gds-transport: "GDS Transport", Arial, sans-serif;

Description

List of font families to use if using GDS Transport (the default font 'stack' for GOV.UK)

Type

List

govuk-font-family-gds-transport

$govuk-font-family-gds-transport: "Source Sans Pro", "Arial", sans-serif;

Description

List of font families to use if using GDS Transport (the default font 'stack' for GOV.UK)

Type

List

govuk-font-family-nta

Deprecated!

To be removed once support for compatibility mode is dropped

$govuk-font-family-nta: "Source Sans Pro", "Arial", sans-serif;

Description

List of font families to use if using NTA (old font 'stack' for GOV.UK)

Type

List

govuk-font-family-nta

Deprecated!

To be removed once support for compatibility mode is dropped

$govuk-font-family-nta: "nta", Arial, sans-serif;

Description

List of font families to use if using NTA (old font 'stack' for GOV.UK)

Type

List

govuk-font-family-nta-tabular

Deprecated!

To be removed once support for compatibility mode is dropped

$govuk-font-family-nta-tabular: "ntatabularnumbers", $govuk-font-family-nta;

Description

List of font families to use if using the 'tabular numbers' subset of NTA (the default font 'stack' for GOV.UK)

Because ntatabularnumbers only includes the digits 0-10, all other glyphs will 'fall-through' the stack to NTA.

Type

List

govuk-font-family-nta-tabular

Deprecated!

To be removed once support for compatibility mode is dropped

$govuk-font-family-nta-tabular: "Source Sans Pro", "Arial", sans-serif;

Description

List of font families to use if using the 'tabular numbers' subset of NTA (the default font 'stack' for GOV.UK)

Because ntatabularnumbers only includes the digits 0-10, all other glyphs will 'fall-through' the stack to NTA.

Type

List

govuk-use-legacy-font

$govuk-use-legacy-font: if((
    $govuk-compatibility-govukfrontendtoolkit or
    $govuk-compatibility-govuktemplate or
    $govuk-compatibility-govukelements
  ), true, false) !default;

Description

Use 'legacy' fonts

Whether or not to use v1 nta font from GOV.UK Elements / Frontend Toolkit, for teams that are migrating to GOV.UK Frontend and may be using components from both places in a single application.

Type

Boolean

govuk-font-family

$govuk-font-family: if($govuk-use-legacy-font,
  $govuk-font-family-nta,
  $govuk-font-family-gds-transport
) !default;

Description

Font families to use for all typography on screen media

Type

List

govuk-font-family-tabular

$govuk-font-family-tabular: if($govuk-use-legacy-font,
  $govuk-font-family-nta-tabular,
  false
) !default;

Description

Font families to use when displaying tabular numbers

Type

List

Used by

govuk-font-family-print

$govuk-font-family-print: sans-serif !default;

Description

Font families to use for print media

Type

List

Used by

govuk-include-default-font-face

$govuk-include-default-font-face: (
  $govuk-font-family == $govuk-font-family-gds-transport
 ) !default;

Description

Include the default @font-face declarations

If you have set $govuk-font-family to something other than $govuk-font-family-gds-transport this option is disabled by default.

Type

Boolean

Used by

govuk-font-weight-regular

$govuk-font-weight-regular: 400 !default;

Description

Font weight for regular typography

Type

Number

Used by

govuk-font-weight-bold

$govuk-font-weight-bold: 700 !default;

Description

Font weight for bold typography

Type

Number

Used by

govuk-typography-use-rem

$govuk-typography-use-rem: if((
    $govuk-compatibility-govukfrontendtoolkit or
    $govuk-compatibility-govuktemplate or
    $govuk-compatibility-govukelements
  ), false, true) !default;

Description

Whether or not to define font sizes in rem, improving accessibility by allowing users to adjust the base font-size. This is enabled by default, unless any of the compatibility mode settings are enabled.

You should make sure that $govuk-root-font-size is set correctly for your project.

Type

Boolean

Used by

govuk-root-font-size

$govuk-root-font-size: 16px !default;

Description

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.

If you are integrating Frontend into an existing project that also uses alphagov/govuk_template and you wish to enable $govuk-typography-use-rem then you should set this to 10px to match the 62.5% (10px) base font size that govuk_template sets on the

element.

Type

Number

Used by

govuk-typography-scale

$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: 24px,
      line-height: 25px
    ),
    tablet: (
      font-size: 36px,
      line-height: 40px
    ),
    print: (
      font-size: 24pt,
      line-height: 1.05
    )
  ),
  27: (
    null: (
      font-size: 18px,
      line-height: 20px
    ),
    tablet: (
      font-size: 27px,
      line-height: 30px
    ),
    print: (
      font-size: 18pt,
      line-height: 1.15
    )
  ),
  24: (
    null: (
      font-size: 18px,
      line-height: 20px
    ),
    tablet: (
      font-size: 24px,
      line-height: 30px
    ),
    print: (
      font-size: 18pt,
      line-height: 1.15
    )
  ),
  19: (
    null: (
      font-size: 16px,
      line-height: 20px
    ),
    tablet: (
      font-size: 19px,
      line-height: 25px
    ),
    print: (
      font-size: 14pt,
      line-height: 1.15
    )
  ),
  16: (
    null: (
      font-size: 14px,
      line-height: 16px
    ),
    tablet: (
      font-size: 16px,
      line-height: 20px
    ),
    print: (
      font-size: 14pt,
      line-height: 1.2
    )
  ),
  14: (
    null: (
      font-size: 12px,
      line-height: 15px
    ),
    tablet: (
      font-size: 14px,
      line-height: 20px
    ),
    print: (
      font-size: 12pt,
      line-height: 1.2
    )
  )
) !default;

Description

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.

Type

Map

Map structure

Map key NameMap key DescriptionMap key TypeMap key Value
$point.$breakpoint.font-size

Font size for $point at $breakpoint

Number none
$point.$breakpoint.line-height

Line height for $point at $breakpoint

Number none
$point.print.font-size

Font size for $point when printing

Number none
$point.print.line-height

Line height for $point when printing

Number none

Used by

Tools

mixins

govuk-compatibility

@mixin govuk-compatibility($product) { ... }

Description

Conditional Compatibility Mixin

Selectively output a block (available to the mixin as @content) if a given $product is also identified as being used in the project.

This can then be used to include styles that are only needed to override styles provided by those other products (e.g. where govuk_template has a very specific link selector that otherwise affects buttons).

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$product

Name of product that we are 'defending' against.

String none

Example

// Override .my-class if GOV.UK Template is also being used
@include govuk-compatibility(govuk_template) {
  .my-class {
    color: inherit;
  }
}

Throws

  • Non existent product

Requires

Used by

govuk-exports

@mixin govuk-exports($name) { ... }

Description

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

parameter Nameparameter Descriptionparameter Typeparameter Default value
$name

Name of module - must be unique within the codebase

String none

Requires

Used by

govuk-if-ie8

@mixin govuk-if-ie8() { ... }

Description

Conditionally include rules only for IE8

Parameters

None.

Example

Usage

.foo {
  min-width: 100px;
  // Specify width for IE8 only
  @include govuk-if-ie8 {
    width: 100px;
  }
}

Requires

govuk-not-ie8

@mixin govuk-not-ie8() { ... }

Description

Conditionally exclude rules for IE8

Parameters

None.

Example

Usage

.foo {
  font-weight: bold;

  // Enhance foo only for modern browsers (not IE8)
  @include govuk-not-ie8 {
    font-family: "Comic Sans MS", "Curlz MT" cursive, sans-serif;
    color: #FF69B4;
  }
}

Requires

variables

[private] _govuk-imported-modules

$_govuk-imported-modules: () !default;

Description

List of modules which have already been exported

Type

List

Used by

functions

govuk-font-url

@function govuk-font-url($filename) { ... }

Description

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

parameter Nameparameter Descriptionparameter Typeparameter Default value
$filename

Font filename

String none

Returns

String

URL for the filename, wrapped in url()

Requires

Used by

iff

@function iff($condition, $if-true) { ... }

Description

Syntactic sugar around Sass' built-in if function that does not require you to pass a value for $if-false.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$condition

Whether to return the value of $if-true

Boolean none
$if-true

Value to return if $condition is truthy

Mixed none

Returns

Mixed

Value of $if-true if $condition is truthy, else null

Used by

govuk-image-url

@function govuk-image-url($Filename) { ... }

Description

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

parameter Nameparameter Descriptionparameter Typeparameter Default value
$Filename

for the image to load

String none

Returns

String

URL for the filename, wrapped in url()

Requires

govuk-em

@function govuk-em($value, $context-font-size) { ... }

Description

Convert pixels to em

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$value

Length in pixels

Number none
$context-font-size

Font size of element

Number none

Returns

Number

Length in ems

govuk-px-to-rem

@function govuk-px-to-rem($value) { ... }

Description

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

parameter Nameparameter Descriptionparameter Typeparameter Default value
$value

Length in pixels

Number none

Returns

Number

Length in rems

Requires

Used by

General

mixins

govuk-main-wrapper

Deprecated!

Replace this mixin with more direct references to the spacing mixins.

@mixin govuk-main-wrapper() { ... }

Parameters

None.

Requires

govuk-main-wrapper--l

Deprecated!

Replace this mixin with more direct references to the spacing mixins.

@mixin govuk-main-wrapper--l() { ... }

Description

Use govuk-main-wrapper--l when you page does not have Breadcrumbs, phase banners or back links.

Parameters

None.

Requires

variables

idsk-brand-colour

$idsk-brand-colour: govuk-colour("blue") !default;

Description

Brand colour

Type

Colour