name: Show password input (experimental)
description: A password input field that allows the password to be shown.
body: |
  Adds a password reveal button to an input that toggles its type from password to text, revealing the password. Does not appear if JavaScript is disabled.

  Uses a visually hidden bit of text to inform screen reader users of the state of the input rather than announcing the content of the password input when toggled.

  This component is currently experimental. If you are using it, please feed back any research findings to the Accounts team.
accessibility_criteria: |
  The component must:

  * indicate to the user that the password has been shown or hidden

  Inputs in the component must:

  * accept focus
  * be focusable with a keyboard
  * be usable with a keyboard
  * be usable with touch
  * indicate when they have focus
  * be recognisable as form input elements
  * have correctly associated labels
  * be of the appropriate type for their use, e.g. password inputs should be of type 'password'

  Buttons in the component 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
govuk_frontend_components:
  - text-input
examples:
  default:
    data:
      label:
        text: Please enter your password
      value: this is my password
  disable_form_submit_check:
    description: The component sets the `autocomplete` attribute on the input to "off" so that browsers don't remember the password. This isn't reliable, so the component reverts the input type back to a password when its parent form is submitted. If this is causing conflicts with other JavaScript on your form, you can set `disable-form-submit-check` to `true` to disable this functionality and implement it yourself.
    data:
      label:
        text: Please enter your password
      value: this is my password
      disable_form_submit_check: true
  set_autocomplete_attribute:
    description: By default, autocomplete is set to `off`. This can be set to `new-password` or `current-password` to help browsers differentiate between new and current passwords.
    data:
      label:
        text: Please enter your password
      autocomplete: "current-password"
      value: this is my password
  with_attributes:
    description: The component accepts many but not all of the options that can be passed to a regular input, including `id`, `name` and `describedby` (not shown).
    data:
      label:
        text: Please enter your password
      value: this is my password
      id: custom_id
      name: custom_name
  with_hint:
    data:
      label:
        text: Please enter your password
      value: this is my password
      hint: Your password must be at least twelve thousand characters
  with_error:
    data:
      label:
        text: Please enter your password
      value: this is my password
      error_message: No it isn't
  with_error_items:
    data:
      label:
        text: Please enter your password
      value: this is my password
      error_items:
      - text: Look I keep telling you
      - text: This isn't your password
  with_data_attributes:
    description: Data attributes can be passed to add to the input element. If the data attribute starts with `data-button-` this attribute will be applied to the show/hide button, instead of the input. Note that if JS is disabled, all attributes are added to the input.
    data:
      label:
        text: Your password
      data:
        example_1: value
        example_2: thing
        button_example_1: wotsit
        button_example_2: doodad