Button

About this component

There are 5 types of button in the Design System:

• primary button
• secondary button
• cancel button
• disabled button
• button styled as a link

When to use buttons

Primary button

This is the default button style. Use this for your main call to action.

Use only one primary button on a page (or section of a page). More than one can confuse users.

<button class="ds_button" type="button">Start now</button>

Cancel button

Use this button for actions that cancel or abandon an action.

A cancel button is usually grouped with a primary button. Follow the guidance on grouping buttons.

<button class="ds_button  ds_button--cancel" type="button">Cancel</button>

Secondary button

Use a secondary button for most other actions.

It has less visual prominence than the primary and cancel buttons.

<button class="ds_button  ds_button--secondary" type="button">View summary</button>

Disabled button

Use this style for buttons in a disabled state. They should be used to show a user that an action is possible but not available to them at that stage in the user journey.

Disabled buttons should be styled differently from active buttons. The button is grey to tell users that the button is not usable.

Disabled buttons can confuse users. Only include them if user research shows that they are helpful in your particular use case.

<button disabled="true" class="ds_button" type="button">Download</button>

Button styled as a link

Buttons can be styled as links. However, you should avoid using these, except if:

• all other button types would be too visually prominent
• the user is being taken to another page to perform an action

For example, the Add more fields pattern uses buttons styled as links for users to change or delete fields.

<button type="button" class="ds_link">Delete</button>

When to use a button versus a hyperlink

You should use a: 

• button when the user is performing an action (either primary, secondary or cancel) 
• standard hyperlink when the user is navigating to a different webpage — for example, to find out more about a topic on GOV.UK   

Links styled as buttons

A hyperlink can be styled to look like a button. Use a link styled as a button when it’s either:

• a link that needs to be more visually prominent than a standard link, like a primary call to action — you should limit using these
• a link that a user would perceive as performing an action — for example, when the user is being launched into a service, such as an eligibility checker, application form or calculator

How to add links styled as buttons

If you're using a link styled as a button because it needs to be more visually prominent than a standard link, you should style the link as a button with the appropriate ds_button CSS classes.

<a href="#" class="ds_button">Get started</a>

If you’re using a link that users would perceive as performing an action, you should announce this as a button to users of assistive technology. To do this, you should:

• style the link as a button with the appropriate ds_button CSS classes
• add a role attribute of button to identify the link as a button to screen readers
• add JavaScript that will activate the button when a user presses either the space key or the enter key, to match the keyboard behaviour of a native button

<a href="#" role="button" class="ds_button">Start now</a>

How to use buttons

Grouping buttons

Use a button group when a button is placed next to other buttons or links. Use a consistent approach to sizing buttons within a group — do not mix button sizes with width modifiers.

Buttons and links within a button group will be stacked on mobile sizes. On larger sizes they are arranged in a row that will overflow.

<div class="ds_button-group">
    <button class="ds_button" type="button">Save changes</button>
    <button class="ds_button  ds_button--cancel" type="button">Cancel</button> 
</div>

A button group can be changed to always remain on a single row by adding the ds_button-group—inline modifier class. At mobile sizes, the contents of the button group take up the full available width.

<div class="ds_button-group  ds_button-group--inline">
    <button class="ds_button" type="button">Save changes</button>
    <button class="ds_button  ds_button--cancel" type="button">Cancel</button>
</div>

Links and buttons styled as links should be placed after all other button styles.

<div class="ds_button-group">
    <button class="ds_button  ds_button--small" type="button">Accept all cookies</button>
    <button class="ds_button  ds_button--small  ds_button--secondary" type="button">Use essential cookies only</button>
    <a href="#">Set cookie preferences</a>
</div>

Writing button text

Write button text in sentence case and describe the action the button performs. For example: 

• ‘Start now’ to launch a user into a service
• ‘Sign in’ to an account a user has created
• ‘Continue’ when the service does not save a user’s information
• ‘Save and continue’ when the service saves a user’s information
• ‘Pay’ to make a payment
• ‘Sign out’ when a user is signed in to an account
• ‘Add another item’ to add another item to a list or a group — follow the guidance for button text in the Add more fields pattern

Placement of buttons

If you’re using buttons in standard content, buttons should: 

• sit under a relevant heading 
• be close to the heading — only 1 or 2 sentences should separate them 

If you’re using buttons in forms, put buttons: 

• underneath the relevant form field — for example, to add more fields 
• after fields or body content, as a call to action once the user has completed the page 

Read more about form structure and form design. 

Width variants

Flexible width

This is the default behaviour with buttons expanding to fit the length of text.

<div>
    <button type="button" class="ds_button">Start now</button>
</div>
<div>
    <button type="button" class="ds_button">Search the fair rent register</button>
</div>

Fixed width

Use fixed-width buttons to force uniformity in button widths.

Button text will wrap onto multiple lines if there is insufficient space.

<div>
    <button type="button" class="ds_button  ds_button--fixed">Start now</button>
</div>
<div>
    <button type="button" class="ds_button  ds_button--fixed">Search the fair rent register</button>
</div>

Maximum width

Use maximum-width buttons for large buttons. These will fill the width of small screens, up to a maximum width of 480px.

<div>
    <button type="button" class="ds_button  ds_button--max">Start now</button>
</div>
<div>
    <button type="button" class="ds_button  ds_button--max">Search the fair rent register</button>
</div>

Size variants

Small buttons

You can use a small button when:

• space is limited
• the action is not the primary action on a page

For example, using small buttons in a cookie banner means the banner takes up less space and does not push the site header too far down the page.

The small button modifier can have any button type or width variant.

<div>
    <button type="button" class="ds_button  ds_button--small">Start now</button>
</div>
<div>
    <button type="button" class="ds_button  ds_button--small  ds_button--max  ds_button--secondary">View summary</button>
</div>
<div>
    <button type="button" class="ds_button  ds_button--small  ds_button--fixed  ds_button--cancel">Cancel</button>
</div>

Buttons with icons

You can add an icon to a button to make an action clearer and help users scan the page. 

The Design System uses Google Material icons. 

Icons must: 

• be recognisable 
• be understandable 
• represent one action only 
• directly relate to the button action and text
• match the label colour 

Do not use icons: 

• as decoration 

• inconsistently — an icon should represent the same action wherever used 

• in buttons styled to look like links 

Buttons with icons can have any size, type or width modifiers applied to them. 

<div>
    <button type="button" class="ds_button  ds_button--has-icon  ds_button--max">
        Search
        <svg class="ds_icon" aria-hidden="true" role="img"><use href="/assets/images/icons/icons.stack.svg#search"></use></svg>
    </button>
</div>
<div>
    <button type="button" class="ds_button  ds_button--small  ds_button--secondary  ds_button--has-icon">
        Search
        <svg class="ds_icon" aria-hidden="true" role="img"><use href="/assets/images/icons/icons.stack.svg#search"></use></svg>
    </button>
</div>
<div>
    <button type="button" class="ds_button  ds_button--cancel  ds_button--fixed  ds_button--has-icon">
        Cancel
        <svg class="ds_icon" aria-hidden="true" role="img"><use href="/assets/images/icons/icons.stack.svg#close"></use></svg>
    </button>
</div>

Icons are tied to the edge of the button and not the text. This includes if the button is full-width. 

You can align the icons to either side of the button.

<div class="ds_button-group">
    <button type="button" class="ds_button  ds_button--secondary  ds_button--has-icon  ds_button--has-icon--left">
        <svg class="ds_icon" aria-hidden="true" role="img"><use href="/assets/images/icons/icons.stack.svg#chevron_left"></use></svg>
        Back
    </button>
    <button type="button" class="ds_button  ds_button--has-icon">
        Next
        <svg class="ds_icon" aria-hidden="true" role="img"><use href="/assets/images/icons/icons.stack.svg#chevron_right"></use></svg>
    </button>
</div>

Check our icons guidance for more information on: 

• icons included in the Design System  
• using icons not included in the Design System 
• sizing icons 

Icon-only buttons

Buttons can contain an icon with no visible text.

Use icon-only buttons where space is limited. Choose icons with clear meanings that are universally understood.

Make sure that users of assistive technology can understand what the button does. For example, by adding some visually hidden text or using aria-label.

<div>
    <button type="button" class="ds_button">
        <span class="visually-hidden">Search</span>
        <svg class="ds_icon" aria-hidden="true" role="img"><use href="/assets/images/icons/icons.stack.svg#search"></use></svg>
    </button>
</div>
<div>
    <button type="button" class="ds_button  ds_button--small  ds_button--cancel">
        <span class="visually-hidden">Close</span>
        <svg class="ds_icon" aria-hidden="true" role="img"><use href="/assets/images/icons/icons.stack.svg#close"></use></svg>
    </button>
</div>

Website analytics

Each button has a data attribute that describes the action.

The Design System’s ‘tracking’ script adds the data attribute.

Use the button component to link to service start pages to improve analytics data.