diff --git a/guide/content/form-elements/password.slim b/guide/content/form-elements/password.slim
new file mode 100644
index 00000000..afe8eb4f
--- /dev/null
+++ b/guide/content/form-elements/password.slim
@@ -0,0 +1,31 @@
+---
+title: Password fields
+---
+
+markdown:
+ This component allows users to enter a password, with an option to show what they’ve entered as plain text.
+
+ Use this component whenever you need users to create or enter a password.
+
+== render('/partials/example.*',
+ caption: 'A default password field',
+ code: default_password)
+
+== render('/partials/example.*',
+ caption: 'A password field with a custom label, caption and hint',
+ code: password_with_a_captioned_heading_label_and_hint) do
+ markdown:
+ The password field's title, caption and hint can be customised in the usual way.
+
+== render('/partials/example.*',
+ caption: 'Password field with custom text',
+ code: password_with_custom_text) do
+ markdown:
+ The component's text can be customised or localised by providing the following arguments:
+
+ ul.govuk-list.govuk-list--bullet
+ li show_password_text
and hide_password_text
set the text on the button
+ li show_password_aria_label_text
and hide_password_aria_label_text
control the text exposed to assistive technologies like screen readers
+ li password_shown_announcement_text
and password_hidden_announcement_text
control announcements made to screen reader users when the button is clicked
+
+== render('/partials/related-navigation.*', links: password_info)
diff --git a/guide/lib/examples/password.rb b/guide/lib/examples/password.rb
new file mode 100644
index 00000000..602a331b
--- /dev/null
+++ b/guide/lib/examples/password.rb
@@ -0,0 +1,31 @@
+module Examples
+ module Password
+ def default_password
+ <<~PASSWORD
+ = f.govuk_password_field :password, label: { text: "Enter your password" }
+ PASSWORD
+ end
+
+ def password_with_a_captioned_heading_label_and_hint
+ <<~PASSWORD
+ = f.govuk_password_field(:pin,
+ label: { text: "Enter your PIN", tag: "h2", size: "l" },
+ caption: { text: "Security", size: "m" },
+ hint: { text: "Your PIN was emailed to you when you registered for this service" })
+ PASSWORD
+ end
+
+ def password_with_custom_text
+ <<~PASSWORD
+ = f.govuk_password_field(:secret_code,
+ label: { text: "Enter your secret code" },
+ show_password_text: "Display",
+ hide_password_text: "Conceal",
+ show_password_aria_label_text: "Display the secret code",
+ hide_password_aria_label_text: "Conceal the secret code",
+ password_shown_announcement_text: "The secret code has been displayed",
+ password_hidden_announcement_text: "The secret code has been concealed")
+ PASSWORD
+ end
+ end
+end
diff --git a/guide/lib/helpers.rb b/guide/lib/helpers.rb
index 57c8b103..4ddf08b2 100644
--- a/guide/lib/helpers.rb
+++ b/guide/lib/helpers.rb
@@ -35,6 +35,7 @@
use_helper Examples::ErrorHandling
use_helper Examples::InjectingContent
use_helper Examples::Localisation
+use_helper Examples::Password
use_helper Setup::FormBuilderObjects
use_helper Setup::ExampleData
diff --git a/guide/lib/helpers/link_helpers.rb b/guide/lib/helpers/link_helpers.rb
index ae8551be..0682b542 100644
--- a/guide/lib/helpers/link_helpers.rb
+++ b/guide/lib/helpers/link_helpers.rb
@@ -24,6 +24,7 @@ def navigation_links
"Checkboxes" => "/form-elements/checkboxes/",
"Date input" => "/form-elements/date-input/",
"File upload" => "/form-elements/file-upload/",
+ "Password fields" => "/form-elements/password/",
"Radios" => "/form-elements/radios/",
"Select" => "/form-elements/select/",
"Submit button" => "/form-elements/submit/",
diff --git a/guide/lib/helpers/person.rb b/guide/lib/helpers/person.rb
index 882fde3a..e9587163 100644
--- a/guide/lib/helpers/person.rb
+++ b/guide/lib/helpers/person.rb
@@ -14,6 +14,13 @@ class Person
:national_insurance_number_without_spacing,
)
+ # password examples
+ attr_accessor(
+ :password,
+ :pin,
+ :secret_code
+ )
+
# width examples
attr_accessor(
:twenty,
diff --git a/guide/lib/helpers/related_info.rb b/guide/lib/helpers/related_info.rb
index 0c7668f8..30e0ded7 100644
--- a/guide/lib/helpers/related_info.rb
+++ b/guide/lib/helpers/related_info.rb
@@ -88,5 +88,13 @@ def file_info
'MDN file upload documentation' => 'https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file'
}
end
+
+ def password_info
+ {
+ 'Form builder documentation for password inputs' => 'https://www.rubydoc.info/gems/govuk_design_system_formbuilder/GOVUKDesignSystemFormBuilder/Builder#govuk_password_field-instance_method',
+ 'GOV.UK design system radios component' => 'https://design-system.service.gov.uk/components/password-input/',
+ 'MDN radio button documentation' => 'https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/password'
+ }
+ end
end
end