Skip to main content
Table of contents

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-brand-colour

Brand colour

Default value
$govuk-brand-colour: govuk-colour("blue");

View source code for _colours-applied.scss on GitHub

$govuk-text-colour

Text colour

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

View source code for _colours-applied.scss on GitHub

$govuk-canvas-background-colour

Canvas background colour

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

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

View source code for _colours-applied.scss on GitHub

$govuk-body-background-colour

Body background colour

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

View source code for _colours-applied.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

Default value
$govuk-print-text-colour: #000000;

View source code for _colours-applied.scss on GitHub

$govuk-secondary-text-colour

Secondary text colour

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

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

View source code for _colours-applied.scss on GitHub

$govuk-focus-colour

Focus colour

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

Default value
$govuk-focus-colour: govuk-colour("yellow");

View source code for _colours-applied.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.

Default value
$govuk-focus-text-colour: govuk-colour("black");

View source code for _colours-applied.scss on GitHub

$govuk-error-colour

Error colour

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

Default value
$govuk-error-colour: govuk-colour("red");

View source code for _colours-applied.scss on GitHub

$govuk-border-colour

Border colour

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

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

View source code for _colours-applied.scss on GitHub

$govuk-input-border-colour

Input border colour

Used for form inputs and controls

Default value
$govuk-input-border-colour: govuk-colour("black");

View source code for _colours-applied.scss on GitHub

$govuk-hover-colour

Input hover colour

Used for hover states on form controls

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

View source code for _colours-applied.scss on GitHub

Link colour

$govuk-link-colour: govuk-colour("blue");

View source code for _colours-applied.scss on GitHub

Visited link colour

$govuk-link-visited-colour: govuk-colour("purple", $legacy: #4c2c92);

View source code for _colours-applied.scss on GitHub

Link hover colour

$govuk-link-hover-colour: govuk-colour("dark-blue", $legacy: "light-blue");

View source code for _colours-applied.scss on GitHub

Active link colour

$govuk-link-active-colour: govuk-colour("black", $legacy: "light-blue");

View source code for _colours-applied.scss on GitHub

$govuk-colours-organisations

Organisation colours

Default value
$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
  )
);

View source code for _colours-organisations.scss on GitHub

$govuk-use-legacy-palette

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.

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

View source code for _colours-palette.scss on GitHub

$govuk-colours

Colour palette

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

View source code for _colours-palette.scss on GitHub

Compatibility

$govuk-compatibility-govukfrontendtoolkit

Compatibility Mode: alphagov/govuk_frontend_toolkit

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

Default value
$govuk-compatibility-govukfrontendtoolkit: false;

View source code for _compatibility.scss on GitHub

$govuk-compatibility-govuktemplate

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.

Default value
$govuk-compatibility-govuktemplate: false;

View source code for _compatibility.scss on GitHub

$govuk-compatibility-govukelements

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.

Default value
$govuk-compatibility-govukelements: false;

View source code for _compatibility.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

Internet Explorer 8

$govuk-is-ie8

Whether the stylesheet being built is targeting Internet Explorer 8.

Default value
$govuk-is-ie8: false;

View source code for _ie8.scss on GitHub

$govuk-ie8-breakpoint

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

Default value
$govuk-ie8-breakpoint: desktop;

View source code for _ie8.scss on GitHub

Measurements

$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: 25%,
  one-third: 33.3333%,
  one-half: 50%,
  two-thirds: 66.6666%,
  three-quarters: 75%,
  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-element-error

Form control border width when in error state

Usage
Warning

Deprecated: Use $govuk-border-width-form-element instead. There should be no difference in thickness for inputs in the error state, in order to maintain a distinct focus state.

Default value
$govuk-border-width-form-element-error: 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

Media queries

$govuk-breakpoints

Breakpoint definitions

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

View source code for _media-queries.scss on GitHub

$govuk-show-breakpoints

Show active breakpoint in top-right corner.

Only use this during local development.

Default value
$govuk-show-breakpoints: false;

View source code for _media-queries.scss on GitHub

Typography

$govuk-font-family-gds-transport

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

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

View source code for _typography-font-families.scss on GitHub

$govuk-font-family-nta

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

Usage
Warning

Deprecated: To be removed once support for compatibility mode is dropped

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

View source code for _typography-font-families.scss on GitHub

$govuk-font-family-nta-tabular

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.

Usage
Warning

Deprecated: To be removed once support for compatibility mode is dropped

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

View source code for _typography-font-families.scss on GitHub

$govuk-use-legacy-font

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.

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

View source code for _typography-font.scss on GitHub

$govuk-font-family

Font families to use for all typography on screen media

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

View source code for _typography-font.scss on GitHub

$govuk-font-family-tabular

Font families to use when displaying tabular numbers

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

View source code for _typography-font.scss on GitHub

$govuk-font-family-print

Font families to use for print media

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

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

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

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-typography-use-rem

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.

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

View source code for _typography-responsive.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.

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.

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: 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
    )
  )
);

View source code for _typography-responsive.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

Compatibility mode

govuk-compatibility

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
Name Description Type Default value
$product Name of product that we are ‘defending’ against. String
Usage
@include govuk-compatibility($product) {
  //..
}
Example:
// Override .my-class if GOV.UK Template is also being used
@include govuk-compatibility(govuk_template) {
  .my-class {
    color: inherit;
  }
}

View source code for _compatibility.scss on GitHub

Internet Explorer 8

govuk-if-ie8

Conditionally include rules only for IE8

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

View source code for _ie8.scss on GitHub

govuk-not-ie8

Conditionally exclude rules for IE8

Usage
@include govuk-not-ie8 {
  //..
}
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;
  }
}

View source code for _ie8.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

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;

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)

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

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 colour

Parameters
Name Description Type Default value
$colour Name of colour from the colour palette ($govuk-colours) String
$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
Example: Using legacy colours from the palette
.foo {
  background-colour: govuk-colour("mid-grey", $legacy: "grey-2");
}
Example: Using legacy colour literals
.foo {
  background-colour: govuk-colour("green", $legacy: #BADA55);
}

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
$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, do not use the non-websafe version for text. Boolean true

View source code for _colour.scss on GitHub

govuk-shade

Make a colour darker by mixing it with black

Parameters
Name Description Type Default value
$colour colour to shade Colour
$percentage percentage of $colour in returned color Number

View source code for _colour.scss on GitHub

govuk-tint

Make a colour lighter by mixing it with white

Parameters
Name Description Type Default value
$colour colour to tint Colour
$percentage percentage of $colour in returned color Number

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-at-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-media-query

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
Name Description Type Default value
$from One of $govuk-breakpoints String or Boolean false
$until One of $govuk-breakpoints String or Boolean false
$and Additional media query parameters String or Boolean false
$media-type Media type: screen, print… String all
Usage
@include govuk-media-query($from: false, $until: false, $and: false, $media-type: "all") {
  //..
}
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;
  }
}

View source code for _media-queries.scss on GitHub

Common link mixin

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

@include govuk-link-common;

View source code for _links.scss on GitHub

Default link style mixin

Provides the default unvisited, visited, hover and active states for links.

If you use this mixin in a component you must also include the govuk-link-common mixin in order to get the focus state.

@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

Muted style link mixin

Used for secondary links on a page - the link will appear in muted colours regardless of visited state.

If you use this mixin in a component you must also include the govuk-link-common mixin in order to get the focus state.

@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

Text style link mixin

Overrides the colour of links to match the text colour. Generally used by 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 in order to get the focus state.

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

View source code for _links.scss on GitHub

No visited state link mixin

Used in cases where it is not helpful to distinguish between visited and non-visited links.

For example, navigation links to pages with dynamic content like admin dashboards. The content on the page is changing all the time, so the fact that you’ve visited it before is not important.

If you use this mixin in a component you must also include the govuk-link-common mixin in order to get the focus state.

@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

Print friendly link mixin

When printing, append the the destination URL to the link text, as long as the URL starts with either /, http:// or https://.

@include govuk-link-print-friendly;

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.sccs) Number
Example:
.element {
  padding: govuk-spacing(5);
  top: govuk-spacing(2) !important; // if `!important` is required
}

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-typography-responsive

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
Name Description Type Default value
$font-map Font map Map
$override-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-typography-responsive($font-map, $override-line-height: false, $important: false);

View source code for _typography.scss on GitHub

govuk-font

Font helper

Parameters
Name Description Type Default value
$size Size of the font as it would appear on desktop - uses the responsive font size map Number
$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

Objects

Layout

govuk-main-wrapper

Usage
Warning

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

@include govuk-main-wrapper;

View source code for _main-wrapper.scss on GitHub

govuk-main-wrapper–l

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

Usage
Warning

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

@include govuk-main-wrapper--l;

View source code for _main-wrapper.scss on GitHub

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