name: Button
description: Use buttons to move though a transaction, aim to use only one button per page.
body: |
  Button text should be short and describe the action the button performs.

  This component is also [extended for use in govspeak](https://components.publishing.service.gov.uk/component-guide/govspeak/button).

  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](https://github.com/alphagov/govspeak).
  (This is a challenge to the reader)
accessibility_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
govuk_frontend_components:
  - button
examples:
  default:
    data:
      text: "Submit"
  link_button:
    data:
      text: "I'm really a link sssh"
      href: "#"
  link_button_target_blank:
    data:
      text: "I'm really a link sssh"
      href: "http://www.gov.uk"
      target: "_blank"
  with_type:
    description: Buttons default to having a type of submit, but in some cases it may be desirable to have a different type.
    data:
      text: "Button type button"
      type: "button"
  start_now_button:
    data:
      text: "Start now"
      href: "#"
      start: true
      rel: "external"
  secondary_button:
    data:
      text: "Secondary button"
      secondary: true
  secondary_quiet_button:
    data:
      text: "Secondary quiet button"
      secondary_quiet: true
  destructive_button:
    data:
      text: "Destructive button"
      destructive: true
  start_now_button_with_info_text:
    data:
      text: "Start now"
      href: "#"
      start: true
      info_text: "Sometimes you want to explain where a user is going to."
  with_margin_bottom:
    description: "Sometimes it's useful to break up a page, for example if a button is at the bottom of a page."
    data:
      text: "Submit"
      margin_bottom: true
  extreme_text:
    data:
      text: "I'm a button with lots of text to test how the component scales at extremes."
      href: "#"
  extreme_text_start_now_button:
    data:
      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:
    data:
      text: "Track this!"
      margin_bottom: true
      data_attributes: {
        "module": "cross-domain-tracking",
        "tracking-code": "GA-123ABC",
        "tracking-name": "transactionTracker"
      }
  with_title_attribute:
    data:
      text: "Click me"
      margin_bottom: true
      title: "A button to click"
  inline_layout:
    description: Buttons will display adjacent to each other until mobile view, when they will appear on top of each other.
    embed: |
      <button class="gem-c-button govuk-button gem-c-button--inline">First button</button>
      <%= component %>
    data:
      text: "Second button"
      inline_layout: true
  with_name_and_value_set:
    description: |
      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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#Notes). Make sure to check your user needs and browser usage.
    data:
      text: "This is the button text"
      value: "this_is_the_value"
      name: "this_is_the_name"
  with_js_classes:
    description: Use `js-` prefixed classes only as interaction hooks – to query and operate on elements via JavaScript
    data:
      text: "Button"
      classes: "js-selector-1 js-selector-2"
  with_aria_label:
    data:
      text: "Button"
      aria_label: "Button with custom label"