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?" }
<%= f.govuk_collection_check_boxes :department_ids, departments, :id, :name, legend: { text: "Which department do you work in?" } %>

Rendered output

Which department do you work in?

HTML output

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
      Which department do you work in?
    </legend>
    <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?" }
<%= 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">
      What is your preferred lunch option?
    </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?" }
<%= 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?" } %>
  <% end %>
<% end %>

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">
      Which languages do you speak?
    </legend>
    <input value="" name="person[languages][]" type="hidden" id="person_languages" />
    <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.

If a checkbox is unchecked when its form is submitted, there is no value submitted to the server to represent its unchecked state

To address the empty submission problem outlined above, Rails generates hidden fields with no value to represent the unchecked state. This is taken care of by default when using govuk_collection_check_boxes and govuk_collection_check_boxes for multiple values. When using govuk_collection_check_boxes for a single value, usually a boolean toggle or confirmation, we need to take an exta step and pass in multiple: false.

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?" }
<%= 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">
      What would you like for lunch on Wednesday?
    </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.

Note that the multiple keyword on govuk_check_boxes_fieldset changes the hidden field’s name attribute to the Rails’ single attribute syntax. It is required to prevent unnecessary hidden fields from being generated.

Input

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

  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,
    1,
    0,
    multiple: false,
    link_errors: true,
    label: { text: "I agree to the terms and conditions" }
<%= f.govuk_check_boxes_fieldset :terms_and_conditions_agreed, multiple: false, legend: { text: 'Terms and conditions', size: 'l' } do %>
  <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>
  <%= f.govuk_check_box :terms_and_conditions_agreed, 1, 0, multiple: false, link_errors: true, label: { text: "I agree to the terms and conditions" } %>
<% end %>

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">
      Terms and conditions
    </legend>
    <div class="govuk-checkboxes" data-module="govuk-checkboxes">
      <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 name="person[terms_and_conditions_agreed]" type="hidden" value="0" />
        <input id="person-terms-and-conditions-agreed-1-field" class="govuk-checkboxes__input" type="checkbox" value="1" name="person[terms_and_conditions_agreed]" />
        <label for="person-terms-and-conditions-agreed-1-field" class="govuk-label govuk-checkboxes__label">
          I agree to the terms and conditions
        </label>
      </div>
    </div>
  </fieldset>
</div>