Skip to main content

This is a guide on using the GOV.UK Design System Form Builder

  1. Index
  2. Check boxes

Checkboxes

The checkboxes component allows users to select one or more options.

Use the checkboxes component when you need to help users:

  • select multiple options from a list
  • toggle a single option on or off

Generating a collection of checkboxes

Data

departments = [
  OpenStruct.new(id: 1, name: 'Sales'),
  OpenStruct.new(id: 2, name: 'Marketing'),
  OpenStruct.new(id: 3, name: 'Finance')
]

Input

= f.govuk_collection_check_boxes :department_ids,
  departments,
  :id,
  :name,
  legend: { text: "Which department do you work in?" }

Rendered output

Departments Which department do you work in?

Select all that apply

HTML output

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
      <h1 class="govuk-fieldset__heading">
        <span class="govuk-caption-m">
          Departments
        </span>
        Which department do you work in?
      </h1>
    </legend>
    <span class="govuk-hint" id="person-department-ids-hint">
      Select all that apply
    </span>
    <div class="govuk-checkboxes" data-module="govuk-checkboxes">
      <input type="hidden" name="person[department_ids][]" value="" />
      <div class="govuk-checkboxes__item">
        <input id="person-department-ids-1-field" class="govuk-checkboxes__input" type="checkbox" value="1" name="person[department_ids][]" />
        <label for="person-department-ids-1-field" class="govuk-label govuk-checkboxes__label">
          Sales
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input id="person-department-ids-2-field" class="govuk-checkboxes__input" type="checkbox" value="2" name="person[department_ids][]" />
        <label for="person-department-ids-2-field" class="govuk-label govuk-checkboxes__label">
          Marketing
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input id="person-department-ids-3-field" class="govuk-checkboxes__input" type="checkbox" value="3" name="person[department_ids][]" />
        <label for="person-department-ids-3-field" class="govuk-label govuk-checkboxes__label">
          Finance
        </label>
      </div>
    </div>
  </fieldset>
</div>

Generating a collection of checkboxes with hints

Data

lunch_options = [
  OpenStruct.new(
    id: 1,
    name: 'Salad',
    description: 'Lettuce, tomato and cucumber'
  ),
  OpenStruct.new(
    id: 2,
    name: 'Jacket potato',
    description: 'With cheese and baked beans'
  )
]

Input

= f.govuk_collection_check_boxes :lunch_ids,
  lunch_options,
  :id,
  :name,
  :description,
  legend: { text: "What is your preferred lunch option?" }

Rendered output

What is your preferred lunch option?

Lettuce, tomato and cucumber
With cheese and baked beans

HTML output

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
      <h1 class="govuk-fieldset__heading">
        What is your preferred lunch option?
      </h1>
    </legend>
    <div class="govuk-checkboxes" data-module="govuk-checkboxes">
      <input type="hidden" name="person[lunch_ids][]" value="" />
      <div class="govuk-checkboxes__item">
        <input id="person-lunch-ids-1-field" class="govuk-checkboxes__input" aria-describedby="person-lunch-ids-1-hint" type="checkbox" value="1" name="person[lunch_ids][]" />
        <label for="person-lunch-ids-1-field" class="govuk-label govuk-checkboxes__label">
          Salad
        </label>
        <span class="govuk-hint govuk-checkboxes__hint" id="person-lunch-ids-1-hint">
          Lettuce, tomato and cucumber
        </span>
      </div>
      <div class="govuk-checkboxes__item">
        <input id="person-lunch-ids-2-field" class="govuk-checkboxes__input" aria-describedby="person-lunch-ids-2-hint" type="checkbox" value="2" name="person[lunch_ids][]" />
        <label for="person-lunch-ids-2-field" class="govuk-label govuk-checkboxes__label">
          Jacket potato
        </label>
        <span class="govuk-hint govuk-checkboxes__hint" id="person-lunch-ids-2-hint">
          With cheese and baked beans
        </span>
      </div>
    </div>
  </fieldset>
</div>

Generating checkboxes with a conditionally-revealed text field

The form builder does not keep track of its contents so to ensure the error summary correctly links to the first check box link_errors must be set to true

When more advanced functionality like conditional fields is required, the govuk_check_boxes_fieldset helper is recommended. Any content passed in via the block will be conditionally revealed when the box is checked.

Input

= f.govuk_check_boxes_fieldset :languages, legend: { text: "Which languages do you speak?", size: "m" } do

  = f.govuk_check_box :languages,
    :english,
    label: { text: "English" },
    link_errors: true,
    hint_text: "Only select English if you have a GCSE at grade C or above"

  = f.govuk_check_box :languages,
    :welsh,
    label: { text: "Welsh" }

  = f.govuk_check_box :languages,
    :gaelic,
    label: { text: "Gaelic" }

  = f.govuk_check_box :languages,
    :other,
    label: { text: "Other" } do

    = f.govuk_text_field :other_language,
      label: { text: "Which additional language do you speak?" }

Rendered output

Which languages do you speak?

Only select English if you have a GCSE at grade C or above

HTML output

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
      <h1 class="govuk-fieldset__heading">
        Which languages do you speak?
      </h1>
    </legend>
    <div class="govuk-checkboxes" data-module="govuk-checkboxes">
      <div class="govuk-checkboxes__item">
        <input id="person-languages-english-field" class="govuk-checkboxes__input" aria-describedby="person-languages-english-hint" type="checkbox" value="english" name="person[languages][]" />
        <label for="person-languages-english-field" class="govuk-label govuk-checkboxes__label">
          English
        </label>
        <span class="govuk-hint govuk-checkboxes__hint" id="person-languages-english-hint">
          Only select English if you have a GCSE at grade C or above
        </span>
      </div>
      <div class="govuk-checkboxes__item">
        <input id="person-languages-welsh-field" class="govuk-checkboxes__input" type="checkbox" value="welsh" name="person[languages][]" />
        <label for="person-languages-welsh-field" class="govuk-label govuk-checkboxes__label">
          Welsh
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input id="person-languages-gaelic-field" class="govuk-checkboxes__input" type="checkbox" value="gaelic" name="person[languages][]" />
        <label for="person-languages-gaelic-field" class="govuk-label govuk-checkboxes__label">
          Gaelic
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input id="person-languages-other-field" class="govuk-checkboxes__input" data-aria-controls="person-languages-other-conditional" type="checkbox" value="other" name="person[languages][]" />
        <label for="person-languages-other-field" class="govuk-label govuk-checkboxes__label">
          Other
        </label>
      </div>
      <div class="govuk-checkboxes__conditional govuk-checkboxes__conditional--hidden" id="person-languages-other-conditional">
        <div class="govuk-form-group">
          <label for="person-other-language-field" class="govuk-label">
            Which additional language do you speak?
          </label>
          <input id="person-other-language-field" class="govuk-input" type="text" name="person[other_language]" />
        </div>
      </div>
    </div>
  </fieldset>
</div>

Small checkboxes

Use standard-sized checkboxes in nearly all cases. However, smaller versions work well on pages where it’s helpful to make them less visually prominent.

For example, on a page of search results, the primary user need is to see the results. Using smaller checkboxes lets users see and change search filters without distracting them from the main content.

Data

lunch_options = [
  OpenStruct.new(
    id: 1,
    name: 'Salad',
    description: 'Lettuce, tomato and cucumber'
  ),
  OpenStruct.new(
    id: 2,
    name: 'Jacket potato',
    description: 'With cheese and baked beans'
  )
]

Input

= f.govuk_collection_check_boxes :wednesday_lunch_ids,
  lunch_options,
  :id,
  :name,
  :description,
  small: true,
  legend: { text: "What would you like for lunch on Wednesday?" }

Rendered output

What would you like for lunch on Wednesday?

Lettuce, tomato and cucumber
With cheese and baked beans

HTML output

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
      <h1 class="govuk-fieldset__heading">
        What would you like for lunch on Wednesday?
      </h1>
    </legend>
    <div class="govuk-checkboxes govuk-checkboxes--small" data-module="govuk-checkboxes">
      <input type="hidden" name="person[wednesday_lunch_ids][]" value="" />
      <div class="govuk-checkboxes__item">
        <input id="person-wednesday-lunch-ids-1-field" class="govuk-checkboxes__input" aria-describedby="person-wednesday-lunch-ids-1-hint" type="checkbox" value="1" name="person[wednesday_lunch_ids][]" />
        <label for="person-wednesday-lunch-ids-1-field" class="govuk-label govuk-checkboxes__label">
          Salad
        </label>
        <span class="govuk-hint govuk-checkboxes__hint" id="person-wednesday-lunch-ids-1-hint">
          Lettuce, tomato and cucumber
        </span>
      </div>
      <div class="govuk-checkboxes__item">
        <input id="person-wednesday-lunch-ids-2-field" class="govuk-checkboxes__input" aria-describedby="person-wednesday-lunch-ids-2-hint" type="checkbox" value="2" name="person[wednesday_lunch_ids][]" />
        <label for="person-wednesday-lunch-ids-2-field" class="govuk-label govuk-checkboxes__label">
          Jacket potato
        </label>
        <span class="govuk-hint govuk-checkboxes__hint" id="person-wednesday-lunch-ids-2-hint">
          With cheese and baked beans
        </span>
      </div>
    </div>
  </fieldset>
</div>

Generating a single checkbox

Single checkboxes can be used to toggle boolean fields. This pattern is most-commonly used for accepting terms and conditions or changing settings

When asking users questions, favour the use of ‘Yes’ and ‘No’ radio buttons. This ensures the user has understood the question and is actively selecting the appropriate answer.

Input

= f.govuk_check_boxes_fieldset :terms_and_conditions_agreed,
  legend: { text: 'Terms and conditions', size: 'l' } do

  = f.hidden_field :terms_and_conditions_agreed, value: false

  p.govuk-body
    | Our terms and conditions contain important information about:

  ul.govuk-list.govuk-list--bullet
    li the application process
    li contacting us
    li our use of your data
    li checking you're safe to work with children

  = f.govuk_check_box :terms_and_conditions_agreed,
    true,
    multiple: false,
    link_errors: true,
    label: { text: 'I agree to the terms and conditions' }

Rendered output

Terms and conditions

Our terms and conditions contain important information about:

  • the application process
  • contacting us
  • our use of your data
  • checking you’re safe to work with children

HTML output

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--l">
      <h1 class="govuk-fieldset__heading">
        Terms and conditions
      </h1>
    </legend>
    <div class="govuk-checkboxes" data-module="govuk-checkboxes">
      <input value="false" type="hidden" name="person[terms_and_conditions_agreed]" id="person_terms_and_conditions_agreed" />
      <p class="govuk-body">
        Our terms and conditions contain important information about:
      </p>
      <ul class="govuk-list govuk-list--bullet">
        <li>
          the application process
        </li>
        <li>
          contacting us
        </li>
        <li>
          our use of your data
        </li>
        <li>
          checking you're safe to work with children
        </li>
      </ul>
      <div class="govuk-checkboxes__item">
        <input id="person-terms-and-conditions-agreed-true-field" class="govuk-checkboxes__input" type="checkbox" value="true" name="person[terms_and_conditions_agreed]" />
        <label for="person-terms-and-conditions-agreed-true-field" class="govuk-label govuk-checkboxes__label">
          I agree to the terms and conditions
        </label>
      </div>
    </div>
  </fieldset>
</div>