1. Collections Component Guide
  2. Button
Component

Button

Use buttons to move though a transaction, aim to use only one button per page.

Button text should be short and describe the action the button performs.

This component is also extended for use in govspeak.

These instances of buttons are added by Content Designers, ideally this duplication would not exist but we currently don’t have shared markup via our components within the generated govspeak. (This is a challenge to the reader)

Search for usage of this component on GitHub.

How it looks (preview) (preview all)

How to call this component

<%= render "govuk_publishing_components/components/button", {
  text: "Submit"
} %>

GOV.UK Design System

This component incorporates components from the GOV.UK Design System:

Accessibility acceptance criteria

The button must:

  • accept focus
  • be focusable with a keyboard
  • indicate when it has focus
  • activate when focused and space is pressed
  • activate when focused and enter is pressed
  • have a role of button
  • have an accessible label

Other examples

With type (preview)

Buttons default to having a type of submit, but in some cases it may be desirable to have a different type.

<%= render "govuk_publishing_components/components/button", {
  text: "Button type button",
  type: "button"
} %>

Start now button (preview)

<%= render "govuk_publishing_components/components/button", {
  text: "Start now",
  href: "#",
  start: true,
  rel: "external"
} %>

Secondary button (preview)

<%= render "govuk_publishing_components/components/button", {
  text: "Secondary button",
  secondary: true
} %>

Secondary quiet button (preview)

<%= render "govuk_publishing_components/components/button", {
  text: "Secondary quiet button",
  secondary_quiet: true
} %>

Secondary solid button (preview)

<%= render "govuk_publishing_components/components/button", {
  text: "Secondary solid button",
  secondary_solid: true
} %>

Destructive button (preview)

<%= render "govuk_publishing_components/components/button", {
  text: "Destructive button",
  destructive: true
} %>

Start now button with info text (preview)

Start now
<%= render "govuk_publishing_components/components/button", {
  text: "Start now",
  href: "#",
  start: true,
  info_text: "Sometimes you want to explain where a user is going to."
} %>

With margin bottom (preview)

The component accepts a number for margin bottom from 0 to 9 (0px to 60px) using the GOV.UK Frontend spacing scale. It defaults to having no margin bottom.

<%= render "govuk_publishing_components/components/button", {
  text: "Submit",
  margin_bottom: 6
} %>

Start now button with info text and margin bottom (preview)

When the component requires margin bottom and has info text, the margin is applied to the info text.

Start now
<%= render "govuk_publishing_components/components/button", {
  text: "Start now",
  href: "#",
  start: true,
  info_text: "Sometimes you want to explain where a user is going to and have a margin bottom",
  margin_bottom: 6
} %>

Extreme text (preview)

<%= render "govuk_publishing_components/components/button", {
  text: "I'm a button with lots of text to test how the component scales at extremes.",
  href: "#"
} %>

Extreme text start now button (preview)

<%= render "govuk_publishing_components/components/button", {
  text: "I'm a start now button with lots of text to test how the component scales at extremes.",
  start: true,
  href: "#"
} %>

With data attributes (preview)

Data attributes can be applied as required. Note that the component does not include built in tracking. If this is required consider using the track click script.

<%= render "govuk_publishing_components/components/button", {
  text: "Track this!",
  margin_bottom: true,
  data_attributes: {
    module: "cross-domain-tracking",
    "tracking-code": "GA-123ABC",
    "tracking-name": "transactionTracker"
  }
} %>

With title attribute (preview)

<%= render "govuk_publishing_components/components/button", {
  text: "Click me",
  margin_bottom: true,
  title: "A button to click"
} %>

Inline layout (preview)

Buttons will display adjacent to each other until mobile view, when they will appear on top of each other.

<button class="gem-c-button govuk-button gem-c-button--inline">First button</button>
<%= render "govuk_publishing_components/components/button", {
  text: "Second button",
  inline_layout: true
} %>

With name and value set (preview)

By default, the button has no value or name set so it will not pass information when the form is submitted. This allows a name and value to be added so a button can add information to the form submission.

Please note that Internet Explorer 6 and 7 have breaking bugs when submitting a form with multiple buttons - this can change what value is submitted by the button. Make sure to check your user needs and browser usage.

<%= render "govuk_publishing_components/components/button", {
  text: "This is the button text",
  value: "this_is_the_value",
  name: "this_is_the_name"
} %>

With js classes (preview)

Use js- prefixed classes only as interaction hooks – to query and operate on elements via JavaScript

<%= render "govuk_publishing_components/components/button", {
  text: "Button",
  classes: "js-selector-1 js-selector-2"
} %>

With aria label (preview)

<%= render "govuk_publishing_components/components/button", {
  text: "Button",
  aria_label: "Button with custom label"
} %>

With aria controls (preview)

Used to identify what element(s) the button controls, this can be useful for users with visual impairment. In the example shown, the button controls the page wrapper with ID wrapper but it could be another identifying attribute.

<%= render "govuk_publishing_components/components/button", {
  text: "Button",
  aria_controls: "wrapper"
} %>

With aria describedby (preview)

Can be used to give context to a button, this will be read after aria-label by a screenreader

<%= render "govuk_publishing_components/components/button", {
  text: "Button",
  aria_describedby: "with_aria_describedby"
} %>