Merge pull request #846 from alphagov/hint-in-radios-and-checkboxes

Allow an optional hint for each radio and checkbox item
alphagov · Jul 25, 2018 · d155120 · d155120
2 parents 8d3f5c1 + 68f8bce
commit d155120
Show file tree

Hide file tree

Showing 13 changed files with 389 additions and 2 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -34,6 +34,12 @@
   colours in their browser, rather than it appearing underlined all the time
   ([PR #926](https://github.com/alphagov/govuk-frontend/pull/926))
 
+- Allow for optional hint for each radio and checkbox item
+
+  You can now pass a hint object (or add in html) to each radio
+  and checkbox item to display the hint
+  ([PR #846](https://github.com/alphagov/govuk-frontend/pull/846))
+
 🔧 Fixes:
 
 - Replace conflicting `js-hidden` class used within the tabs component with a new modifier class.

diff --git a/src/components/checkboxes/README.md b/src/components/checkboxes/README.md
@@ -155,6 +155,82 @@ Find out when to use the checkboxes component in your service in the [GOV.UK Des
       ]
     }) }}
 
+### Checkboxes with hints on items
+
+[Preview this example in the Frontend review app](http://govuk-frontend-review.herokuapp.com/components/checkboxes/with-hints-on-items/preview)
+
+#### Markup
+
+    <div class="govuk-form-group">
+
+      <fieldset class="govuk-fieldset">
+
+      <legend class="govuk-fieldset__legend">
+        <h1 class="govuk-fieldset__heading">
+          How do you want to sign in?
+        </h1>
+      </legend>
+
+      <div class="govuk-checkboxes">
+
+        <div class="govuk-checkboxes__item">
+          <input class="govuk-checkboxes__input" id="government-gateway" name="gateway" type="checkbox" value="gov-gateway" aria-describedby="government-gateway-item-hint">
+          <label class="govuk-label govuk-checkboxes__label" for="government-gateway">
+            Sign in with Government Gateway
+          </label>
+          <span id="government-gateway-item-hint" class="govuk-hint govuk-checkboxes__hint">
+            You’ll have a user ID if you’ve registered for Self Assessment or filed a tax return online before.
+          </span>
+        </div>
+
+        <div class="govuk-checkboxes__item">
+          <input class="govuk-checkboxes__input" id="govuk-verify" name="verify" type="checkbox" value="gov-verify" aria-describedby="govuk-verify-item-hint">
+          <label class="govuk-label govuk-checkboxes__label" for="govuk-verify">
+            Sign in with GOV.UK Verify
+          </label>
+          <span id="govuk-verify-item-hint" class="govuk-hint govuk-checkboxes__hint">
+            You’ll have an account if you’ve already proved your identity with either Barclays, CitizenSafe, Digidentity, Experian, Post Office, Royal Mail or SecureIdentity.
+          </span>
+        </div>
+
+      </div>
+      </fieldset>
+
+    </div>
+
+#### Macro
+
+    {% from "checkboxes/macro.njk" import govukCheckboxes %}
+
+    {{ govukCheckboxes({
+      "fieldset": {
+        "legend": {
+          "text": "How do you want to sign in?",
+          "isPageHeading": true
+        }
+      },
+      "items": [
+        {
+          "name": "gateway",
+          "id": "government-gateway",
+          "value": "gov-gateway",
+          "text": "Sign in with Government Gateway",
+          "hint": {
+            "text": "You’ll have a user ID if you’ve registered for Self Assessment or filed a tax return online before."
+          }
+        },
+        {
+          "name": "verify",
+          "id": "govuk-verify",
+          "value": "gov-verify",
+          "text": "Sign in with GOV.UK Verify",
+          "hint": {
+            "text": "You’ll have an account if you’ve already proved your identity with either Barclays, CitizenSafe, Digidentity, Experian, Post Office, Royal Mail or SecureIdentity."
+          }
+        }
+      ]
+    }) }}
+
 ### Checkboxes with disabled item
 
 [Preview this example in the Frontend review app](http://govuk-frontend-review.herokuapp.com/components/checkboxes/with-disabled-item/preview)
@@ -775,6 +851,18 @@ If you are using Nunjucks,then macros take the following arguments
 
 <tr class="govuk-table__row">
 
+<th class="govuk-table__header" scope="row">items.{}.hint</th>
+
+<td class="govuk-table__cell ">object</td>
+
+<td class="govuk-table__cell ">No</td>
+
+<td class="govuk-table__cell ">Provide optional hint to each checkbox item. See `hint` component for more details.</td>
+
+</tr>
+
+<tr class="govuk-table__row">
+
 <th class="govuk-table__header" scope="row">items.{}.checked</th>
 
 <td class="govuk-table__cell ">boolean</td>

diff --git a/src/components/checkboxes/README.njk b/src/components/checkboxes/README.njk
@@ -185,6 +185,20 @@
         html: 'Provide additional attributes to each checkbox item label. See <a href="../label/README.md#component-arguments">label</a> component for more details.'
       }
     ],
+    [
+      {
+        text: 'items.{}.hint'
+      },
+      {
+        text: 'object'
+      },
+      {
+        text: 'No'
+      },
+      {
+        html: 'Provide optional hint to each checkbox item. See `hint` component for more details.'
+      }
+    ],
     [
       {
         text: 'items.{}.checked'

diff --git a/src/components/checkboxes/_checkboxes.scss b/src/components/checkboxes/_checkboxes.scss
@@ -66,6 +66,12 @@
     touch-action: manipulation;
   }
 
+  .govuk-checkboxes__hint {
+    display: block;
+    padding-right: $govuk-checkboxes-label-padding-left-right;
+    padding-left: $govuk-checkboxes-label-padding-left-right;
+  }
+
   .govuk-checkboxes__input + .govuk-checkboxes__label::before {
     content: "";
     box-sizing: border-box;

diff --git a/src/components/checkboxes/checkboxes.yaml b/src/components/checkboxes/checkboxes.yaml
@@ -43,6 +43,26 @@ examples:
         value: irish
         text: Irish
 
+- name: with hints on items
+  data:
+    fieldset:
+      legend:
+        text: How do you want to sign in?
+        isPageHeading: true
+    items:
+      - name: gateway
+        id: government-gateway
+        value: gov-gateway
+        text: Sign in with Government Gateway
+        hint:
+          text: You’ll have a user ID if you’ve registered for Self Assessment or filed a tax return online before.
+      - name: verify
+        id: govuk-verify
+        value: gov-verify
+        text: Sign in with GOV.UK Verify
+        hint:
+          text: You’ll have an account if you’ve already proved your identity with either Barclays, CitizenSafe, Digidentity, Experian, Post Office, Royal Mail or SecureIdentity.
+
 - name: with disabled item
   data:
     name: colours

diff --git a/src/components/checkboxes/template.njk b/src/components/checkboxes/template.njk
@@ -48,18 +48,30 @@
     {% set id = item.id if item.id else idPrefix + "-" + loop.index %}
     {% set name = item.name if item.name else params.name %}
     {% set conditionalId = "conditional-" + id %}
+    {% set hasHint = true if item.hint.text or item.hint.html %}
+    {% set itemHintId = id + '-item-hint' %}
     <div class="govuk-checkboxes__item">
       <input class="govuk-checkboxes__input" id="{{ id }}" name="{{ name }}" type="checkbox" value="{{ item.value }}"
       {{-" checked" if item.checked }}
       {{-" disabled" if item.disabled }}
-      {%- if item.conditional %} data-aria-controls="{{ conditionalId }}"{% endif -%}>
+      {%- if item.conditional %} data-aria-controls="{{ conditionalId }}"{% endif -%}
+      {%- if hasHint %} aria-describedby="{{ itemHintId }}"{% endif -%}>
       {{ govukLabel({
         html: item.html,
         text: item.text,
         classes: 'govuk-checkboxes__label',
         attributes: item.label.attributes,
         for: id
       }) | indent(6) | trim }}
+      {%- if hasHint %}
+      {{ govukHint({
+        id: itemHintId,
+        classes: 'govuk-checkboxes__hint',
+        attributes: item.hint.attributes,
+        html: item.hint.html,
+        text: item.hint.text
+      }) | indent(6) | trim }}
+      {%- endif %}
     </div>
     {% if item.conditional %}
       <div class="govuk-checkboxes__conditional{% if not item.checked %} govuk-checkboxes__conditional--hidden{% endif %}" id="{{ conditionalId }}">

diff --git a/src/components/checkboxes/template.test.js b/src/components/checkboxes/template.test.js
@@ -255,6 +255,60 @@ describe('Checkboxes', () => {
     })
   })
 
+  describe('when they include a hint', () => {
+    it('it renders the hint text', () => {
+      const $ = render('checkboxes', {
+        name: 'gov',
+        items: [
+          {
+            value: 'value',
+            text: 'This is text',
+            hint: {
+              text: 'This is a hint'
+            }
+          }
+        ]
+      })
+      expect($('.govuk-checkboxes__hint').text()).toContain('This is a hint')
+    })
+
+    it('it renders the correct id attribute for the hint', () => {
+      const $ = render('checkboxes', {
+        name: 'gov',
+        items: [
+          {
+            value: 'value',
+            text: 'This is text',
+            id: 'item-id',
+            hint: {
+              text: 'This is a hint'
+            }
+          }
+        ]
+      })
+
+      expect($('.govuk-checkboxes__hint').attr('id')).toBe('item-id-item-hint')
+    })
+
+    it('the input describedBy attribute matches the item hint id', () => {
+      const $ = render('checkboxes', {
+        name: 'gov',
+        items: [
+          {
+            value: 'value',
+            text: 'This is text',
+            id: 'item-id',
+            hint: {
+              text: 'This is a hint'
+            }
+          }
+        ]
+      })
+
+      expect($('.govuk-checkboxes__input').attr('aria-describedby')).toBe('item-id-item-hint')
+    })
+  })
+
   describe('render conditionals', () => {
     it('hidden by default when not checked', () => {
       const $ = render('checkboxes', {

diff --git a/src/components/radios/README.md b/src/components/radios/README.md
@@ -425,6 +425,80 @@ Find out when to use the radios component in your service in the [GOV.UK Design
       ]
     }) }}
 
+### Radios with hints on items
+
+[Preview this example in the Frontend review app](http://govuk-frontend-review.herokuapp.com/components/radios/with-hints-on-items/preview)
+
+#### Markup
+
+    <div class="govuk-form-group">
+
+      <fieldset class="govuk-fieldset">
+
+      <legend class="govuk-fieldset__legend">
+        <h1 class="govuk-fieldset__heading">
+          How do you want to sign in?
+        </h1>
+      </legend>
+
+      <div class="govuk-radios">
+
+        <div class="govuk-radios__item">
+          <input class="govuk-radios__input" id="gov-1" name="gov" type="radio" value="gateway" aria-describedby="gov-1-item-hint">
+          <label class="govuk-label govuk-radios__label" for="gov-1">
+            Sign in with Government Gateway
+          </label>
+          <span id="gov-1-item-hint" class="govuk-hint govuk-radios__hint">
+            You&#39;ll have a user ID if you&#39;ve registered for Self Assessment or filed a tax return online before.
+          </span>
+        </div>
+
+        <div class="govuk-radios__item">
+          <input class="govuk-radios__input" id="gov-2" name="gov" type="radio" value="verify" aria-describedby="gov-2-item-hint">
+          <label class="govuk-label govuk-radios__label" for="gov-2">
+            Sign in with GOV.UK Verify
+          </label>
+          <span id="gov-2-item-hint" class="govuk-hint govuk-radios__hint">
+            You’ll have an account if you’ve already proved your identity with either Barclays, CitizenSafe, Digidentity, Experian, Post Office, Royal Mail or SecureIdentity.
+          </span>
+        </div>
+
+      </div>
+      </fieldset>
+
+    </div>
+
+#### Macro
+
+    {% from "radios/macro.njk" import govukRadios %}
+
+    {{ govukRadios({
+      "idPrefix": "gov",
+      "name": "gov",
+      "fieldset": {
+        "legend": {
+          "text": "How do you want to sign in?",
+          "isPageHeading": true
+        }
+      },
+      "items": [
+        {
+          "value": "gateway",
+          "text": "Sign in with Government Gateway",
+          "hint": {
+            "text": "You'll have a user ID if you've registered for Self Assessment or filed a tax return online before."
+          }
+        },
+        {
+          "value": "verify",
+          "text": "Sign in with GOV.UK Verify",
+          "hint": {
+            "text": "You’ll have an account if you’ve already proved your identity with either Barclays, CitizenSafe, Digidentity, Experian, Post Office, Royal Mail or SecureIdentity."
+          }
+        }
+      ]
+    }) }}
+
 ### Radios without fieldset
 
 [Preview this example in the Frontend review app](http://govuk-frontend-review.herokuapp.com/components/radios/without-fieldset/preview)
@@ -737,6 +811,18 @@ If you are using Nunjucks,then macros take the following arguments
 
 <tr class="govuk-table__row">
 
+<th class="govuk-table__header" scope="row">items.{}.hint</th>
+
+<td class="govuk-table__cell ">object</td>
+
+<td class="govuk-table__cell ">No</td>
+
+<td class="govuk-table__cell ">Provide optional hint to each radio item. See `hint` component for more details.</td>
+
+</tr>
+
+<tr class="govuk-table__row">
+
 <th class="govuk-table__header" scope="row">items.{}.divider</th>
 
 <td class="govuk-table__cell ">string</td>

diff --git a/src/components/radios/README.njk b/src/components/radios/README.njk
@@ -184,6 +184,20 @@ Let users select a single option from a list.
         html: 'Provide additional attributes to each radio item label. See <a href="../label/README.md#component-arguments">label</a> component for more details.'
       }
     ],
+    [
+      {
+        text: 'items.{}.hint'
+      },
+      {
+        text: 'object'
+      },
+      {
+        text: 'No'
+      },
+      {
+        text: 'Provide optional hint to each radio item. See `hint` component for more details.'
+      }
+    ],
     [
       {
         text: 'items.{}.divider'