Setup guides

Production

This guide explains how to set up your project so you can start using the styles and coded examples in the GOV.UK Design System in production.

If you’ve used GOV.UK Elements, GOV.UK Template or the GOV.UK Frontend Toolkit before, you might also find it useful to read the guide to Migrate from our old frameworks.

Include GOV.UK Frontend in your project

To start using GOV.UK styles, components and patterns contained here, you’ll need to include GOV.UK Frontend in your project.

There are 2 ways to include GOV.UK Frontend in your project. You can either install it using node package manager (npm) or include the compiled files in your application.

Option 1: install using npm

We recommend installing GOV.UK Frontend using npm.

Using this option, you will be able to:

• selectively include the CSS for individual components
• selectively include the JavaScript individual components for
• build your own styles or components based on the palette or typography and spacing mixins
• customise the build (for example, overriding colours or enabling global styles)
• use our Nunjucks template and macros if your environment supports them

Option 2: include compiled files

If your project does not use npm, or if you want to try out GOV.UK Frontend in your project without installing it through npm, you can download and include compiled stylesheets, JavaScript and the asset files.

Using this option, you will be able to include all the CSS and JavaScript of GOV.UK Frontend in your project.

You will not be able to:

• selectively include the CSS for individual components
• selectively include the JavaScript for individual components
• build your own styles or components based on the palette or typography and spacing mixins
• customise the build, for example, overriding colours or enabling global styles
• use the component Nunjucks templates

Start using the GOV.UK page template

You can set up a basic page that is consistent with GOV.UK branding by using the GOV.UK page template.

Styling page elements

The Design System provides CSS classes for styling content, instead of global styles.

The class names follow the Block Element Modifier (BEM) naming convention. This can look a bit daunting at first, but it makes robust code that’s easy to maintain.

Explore the Styles section of the Design System to see what classes are available.

Using components

The components in the Design System are designed to be accessible and responsive.

You can use them in your live application as either:

• HTML
• our Nunjucks macros, if you’ve installed GOV.UK Frontend using npm and your application uses Node.js

You can get the code from the HTML or Nunjucks tabs below any examples:

Open this example in a new tab

HTML

<button type="submit" class="govuk-button" data-module="govuk-button">
  Save and continue
</button>

Nunjucks

Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as “Required” in the option description.

If you’re using Nunjucks macros in production with “html” options, or ones ending with “html”, you must sanitise the HTML to protect against cross-site scripting exploits.

Name	Type	Description
element	string	HTML element for the button component – input, button or a. In most cases you will not need to set this as it will be configured automatically if href is provided. This parameter will be removed in the next major version.
text	string	Required. If html is set, this is not required. Text for the input, button or a element. If html is provided, the text option will be ignored and element will be automatically set to "button" unless href is also set, or it has already been defined.
html	string	Required. If text is set, this is not required. HTML for the button or a element only. If html is provided, the text option will be ignored and element will be automatically set to "button" unless href is also set, or it has already been defined. This option has no effect if element is set to "input".
name	string	Name for the input or button. This has no effect on a elements.
type	string	Type for the input or button element – "button", "submit" or "reset". Defaults to "submit". This has no effect on a elements.
value	string	Value for the button element only. This has no effect on a or input elements.
disabled	boolean	Whether the button component should be disabled. For input and button elements, disabled and aria-disabled attributes will be set automatically. This has no effect on a elements.
href	string	The URL that the button component should link to. If this is set, element will be automatically set to "a" if it has not already been defined.
classes	string	Classes to add to the button component.
attributes	object	HTML attributes (for example data attributes) to add to the button component.
preventDoubleClick	boolean	Prevent accidental double clicks on submit buttons from submitting forms multiple times.
isStartButton	boolean	Use for the main call to action on your service’s start page.
id	string	The ID of the button.

{% from "govuk/components/button/macro.njk" import govukButton %}

{{ govukButton({
  text: "Save and continue"
}) }}

Need help?

If you’ve got a question about the GOV.UK Design System, contact the team.