Setup - Production code

The code you need to start building user interfaces for NHS websites and services.

Include the NHS.UK frontend library in your project

To start using the NHS website styles, components and patterns contained here, you’ll need to include the NHS.UK frontend library in your project.

There are 2 ways to do this. 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 the NHS.UK frontend library using npm.

Using this option, you will be able to:

  • selectively include the CSS or 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

Option 2: include compiled files

If your project does not use npm, or if you want to try out the NHS.UK frontend library 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 the NHS.UK frontend library in your project.

You will not be able to:

  • selectively include the CSS or 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

Styling page elements

The service manual 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 service manual to see what classes are available.

Using components

The components in the service manual are designed to be accessible and responsive. There are 2 ways to implement them in your application.

You can either use HTML or, if you're using Nunjucks with node.js and you installed the NHS.UK frontend library using npm, you can use a Nunjucks Macro.

You can get the code from the HTML or Nunjucks tabs below the examples on our component pages, like this example of a button.

Open this default buttons example in new window
Copy default buttons code
<button class="nhsuk-button" type="submit">
  Save and continue
</button>
Close default buttons code
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.

Nunjucks arguments for default buttons
Name Type Required Description
Name element Type string Required false Description Whether to use an `input`, `button` or `a` element to create the button. In most cases you will not need to set this as it will be configured automatically if you use `href` or `html`.
Name text Type string Required true Description If `html` is set, this is not required. Text for the button or link. If `html` is provided, the `text` argument will be ignored and `element` will be automatically set to `button` unless `href` is also set, or it has already been defined. This argument has no effect if `element` is set to `input`.
Name html Type string Required true Description If `text` is set, this is not required. HTML for the button or link. If `html` is provided, the `text` argument will be ignored and `element` will be automatically set to `button` unless `href` is also set, or it has already been defined. This argument has no effect if `element` is set to `input`.
Name name Type string Required false Description Name for the `input` or `button`. This has no effect on `a` elements.
Name type Type string Required false Description Type of `input` or `button` – `button`, `submit` or `reset`. Defaults to `submit`. This has no effect on `a` elements.
Name value Type string Required false Description Value for the `button` tag. This has no effect on `a` or `input` elements.
Name disabled Type boolean Required false Description Whether the button should be disabled. For button and input elements, `disabled` and `aria-disabled` attributes will be set automatically.
Name href Type string Required false Description The URL that the button should link to. If this is set, `element` will be automatically set to `a` if it has not already been defined.
Name classes Type string Required false Description Classes to add to the button component.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the button component.
Copy default buttons code
{% from 'button/macro.njk' import button %}

{{ button({
  "text": "Save and continue"
}) }}
Close default buttons code

Using Nunjucks macros

A Nunjucks macro is a simple template that generates more complex HTML.

Nunjucks macros save you time by managing repetitive or error-prone tasks, like linking form labels to their controls.

Nunjucks macros also make it easier to keep your application up to date. You can run a command to update component code instead of having to manually update your HTML.

To use Nunjucks macros in your application, you’ll need to setup Nunjucks views to point to the location of NHS.UK frontend components, which is node_modules/nhsuk-frontend/packages/components/.

To include a specific component macro in your page template, you need to import the macro.

For example, to use the button macro, use the import statement % from 'node_modules/nhsuk-frontend/packages/components/button/macro.njk' import button %}.

If you’re using Nunjucks macros in production, be aware that using html arguments or ones ending with html can be a security risk. The Nunjucks templating documentation has guidance on how to mitigate the risks.

Keeping your code up to date

We update the NHS.UK frontend library from time to time. Check for recent releases in the NHS.UK frontend changelog.

Updated: January 2020