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
<button class="hse-button" type="submit">
Save and continue
</button>
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 | 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. |
Name preventDoubleClick | Type boolean | Required false | Description Prevent accidental double clicks on submit buttons from submitting forms multiple times |
{% from 'button/macro.njk' import button %}
{{ button({
"text": "Save and continue"
}) }}
When to use a primary button
A primary button is a call-to-action (CTA) 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
<button class="hse-button hse-button--secondary" type="submit">
Find my location
</button>
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 | 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. |
Name preventDoubleClick | Type boolean | Required false | Description Prevent accidental double clicks on submit buttons from submitting forms multiple times |
{% from 'button/macro.njk' import button %}
{{ button({
"text": "Find my location",
"classes": "hse-button--secondary"
}) }}
When to use a secondary button
A secondary button is also a CTA button.
Use a secondary button on pages that have more than 1 CTA, or when users are not noticing standard link text.
More about when to use and not use buttons.
Text button
<button class="hse-button hse-button--text" type="submit">
Find my location
</button>
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 | 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. |
Name preventDoubleClick | Type boolean | Required false | Description Prevent accidental double clicks on submit buttons from submitting forms multiple times |
{% from 'button/macro.njk' import button %}
{{ button({
"text": "Find my location",
"classes": "hse-button--text"
}) }}
When to use a text button
Use a text button in dialogs. A dialog is a type of modal window. It appears in front of content to provide users with important information or to ask for a decision.
A text button is different from a link. The clickable area is larger than a link. Users can still see the button shape in its pressed (active) or hover state.
When not to use a text button
Do not use a text button for a CTA. Use a primary or secondary button instead.
More about when to use and not use buttons.
White button on solid background colour (inverse button)
<button class="hse-button hse-button--reverse" type="submit">
Save and continue
</button>
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 | 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. |
Name preventDoubleClick | Type boolean | Required false | Description Prevent accidental double clicks on submit buttons from submitting forms multiple times |
{% from 'button/macro.njk' import button %}
{{ button({
"text": "Save and continue",
"classes": "hse-button--reverse"
}) }}
When to use buttons
Use buttons to start or save transactional journeys, such as applications or booking systems.
When not to use buttons
Do not use buttons as links:
- to pages which are not part of your user journey
- from 1 flat content page to another
- to external websites
Try not to have multiple buttons on 1 page.
Start with one thing per page - gov.uk
How to use buttons
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.
Buttons have 5 states:
- default
- hover
- pressed (active)
- focus
- disabled
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.
The NHS has developed disabled versions of the 4 buttons but have not tested them yet.
Latest NHS disabled button code - github.com
Accessibility
Make sure the text you use describes the action.
All 4 pressed (active) buttons pass AAA guidelines for colour contrast. The colour contrast ratio between text and background colour is as follows:
- primary button: 7.12:1
- secondary button: 6.43:1
Please note that the disabled versions of the 4 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.
Research
We based our buttons on the NHS designs. They made their buttons more "button-like" by rounding the corners (adding corner radiuses). There is testing and research to suggest that rounded corners make things more clickable.
Updated: September 2023