Form elements - Buttons

Use buttons to help users carry out an action on a page like starting an application or saving their progress.

We have 3 buttons

Primary 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

When to use a primary button

Use a primary button to help users carry out an action on a page like starting an application or saving their progress.

More about when to use and not use buttons.

Secondary button

Open this secondary buttons example in new window
Copy secondary buttons code
<button class="nhsuk-button nhsuk-button--secondary" type="submit">
  Find my location
</button>
Close secondary 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 secondary 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 secondary buttons code
{% from 'button/macro.njk' import button %}

{{ button({
  "text": "Find my location",
  "classes": "nhsuk-button--secondary"
}) }}
Close secondary buttons code

When to use a secondary button

Use a secondary button on pages that have more than 1 action or when users aren't noticing standard link text.

More about when to use and not use buttons.

White button on solid background colour (reverse button)

Open this reverse buttons example in new window
Copy reverse buttons code
<button class="nhsuk-button nhsuk-button--reverse" type="submit">
  Save and continue
</button>
Close reverse 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 reverse 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 reverse buttons code
{% from 'button/macro.njk' import button %}

{{ button({
  "text": "Save and continue",
  "classes": "nhsuk-button--reverse"
}) }}
Close reverse buttons code

When to use a white button on solid background colour

White buttons on solid background colour are good on components like interruption cards where link text, primary and secondary buttons would be lost. (There's an example on Find out why your NHS data matters.)

More about when to use and not use buttons.

When to use buttons

Use buttons to start or save transactional journeys.

When not to use buttons

Do not use buttons as links:

  • to pages which aren't part of your user journey
  • from 1 flat content page to another
  • to external websites

Try not to have multiple buttons on 1 page. Follow GOV.UK guidance on One thing per page.

How to use buttons

The GOV.UK Design System suggests using a button to help users carry out an action on a page like starting an application or saving their progress.

Write button text in sentence case and describe the action the button performs. For example "Save and continue" or "Start now".

Align the primary action button to the left edge of your form.

Disabled buttons

Disabled buttons have poor contrast and can confuse some users. Only use them if user research shows it makes things easier for users to understand.

We have developed disabled versions of the 3 buttons but we haven't tested them yet. You can get the latest disabled button code in the NHS.UK frontend library in GitHub.

Accessibility

Make sure the text you use describes the action.

All 3 active buttons pass AAA guidelines for colour contrast. The colour contrast ratio between text and background colour is as follows:

  • primary button 5.12:1
  • secondary button 7.75:1
  • white button on solid background colour 14.42:1

Please note that the disabled versions of the 3 buttons do not meet accessibility colour contrast ratios. If your team has discovered a user need for disabled buttons, use them carefully and test them with users with access needs.

Research

We based our buttons on the GOV.UK designs. But because our logo is a blue rectangle and a number of our components (including panel headings) have squared edges, we decided that GOV.UK buttons didn’t stand out enough. The square buttons didn't look clickable next to the other square components.

We made the buttons more "buttony" by rounding the corners (adding corner radiuses). There is research to suggest that rounded corners make things more clickable.

Our testing confirmed this. Users were able to complete tasks using buttons and they didn’t confuse them with non-clickable components.

Have you tested this component?

If so, please share your research findings and let us know how it has worked for you. This will help us improve it for everyone.

Before you start, you will need a GitHub account. It's an open forum where we collect feedback.

If you have any questions, you can message us on Slack. You will need a Slack account if you do not have one. Or you can contact us by email.

Updated: February 2019