Checkboxes
Checkboxes allow users to:
By default the form builder’s checkbox helpers will automatically inject a
hidden field. The hidden field ensures that a parameter is always submitted
with the form even when no checkboxes have been checked, allowing options
to be deselected. The
hidden field can be toggled using the multiple
keyword
argument.
Generating a collection of checkboxes
Data
department = Struct.new(:id, :name, keyword_init: true)
departments = [
department.new(id: 1, name: 'Sales'),
department.new(id: 2, name: 'Marketing'),
department.new(id: 3, name: 'Finance')
]
Input
= f.govuk_collection_check_boxes :department_ids,
departments,
:id,
:name,
caption: nil,
legend: { text: "Which departments do you work in?" },
hint: { text: "Select all departments that apply" }
<%= f.govuk_collection_check_boxes :department_ids, departments, :id, :name, caption: nil, legend: { text: "Which departments do you work in?" }, hint: { text: "Select all departments that apply" } %>
Output
<div class="govuk-form-group">
<fieldset class="govuk-fieldset" aria-describedby="person-department-ids-hint">
<legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
Which departments do you work in?
</legend>
<div class="govuk-hint" id="person-department-ids-hint">
Select all departments that apply
</div>
<div class="govuk-checkboxes" data-module="govuk-checkboxes">
<input type="hidden" name="person[department_ids][]" value="" autocomplete="off" />
<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_option = Struct.new(:id, :name, :description, keyword_init: true)
lunch_options = [
lunch_option.new(
id: 1,
name: 'Salad',
description: 'Lettuce, tomato and cucumber'
),
lunch_option.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,
hint: { text: "Select all options you are happy to eat" },
legend: { text: "What are your preferred lunch options?" }
<%= f.govuk_collection_check_boxes :lunch_ids, lunch_options, :id, :name, :description, hint: { text: "Select all options you are happy to eat" }, legend: { text: "What are your preferred lunch options?" } %>
Output
<div class="govuk-form-group">
<fieldset class="govuk-fieldset" aria-describedby="person-lunch-ids-hint">
<legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
What are your preferred lunch options?
</legend>
<div class="govuk-hint" id="person-lunch-ids-hint">
Select all options you are happy to eat
</div>
<div class="govuk-checkboxes" data-module="govuk-checkboxes">
<input type="hidden" name="person[lunch_ids][]" value="" autocomplete="off" />
<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>
<div class="govuk-hint govuk-checkboxes__hint" id="person-lunch-ids-1-hint">
Lettuce, tomato and cucumber
</div>
</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>
<div class="govuk-hint govuk-checkboxes__hint" id="person-lunch-ids-2-hint">
With cheese and baked beans
</div>
</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 checkbox
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 %>
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][]" autocomplete="off" 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>
<div class="govuk-hint govuk-checkboxes__hint" id="person-languages-english-hint">
Only select English if you have a GCSE at grade C or above
</div>
</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_option = Struct.new(:id, :name, :description, keyword_init: true)
lunch_options = [
lunch_option.new(
id: 1,
name: 'Salad',
description: 'Lettuce, tomato and cucumber'
),
lunch_option.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?" } %>
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="" autocomplete="off" />
<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>
<div class="govuk-hint govuk-checkboxes__hint" id="person-wednesday-lunch-ids-1-hint">
Lettuce, tomato and cucumber
</div>
</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>
<div class="govuk-hint govuk-checkboxes__hint" id="person-wednesday-lunch-ids-2-hint">
With cheese and baked beans
</div>
</div>
</div>
</fieldset>
</div>
Generating a single checkbox
Single checkboxes are usually used for boolean fields like accepting terms and conditions or toggling a setting.
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 in this example multiple: false
is passed to
both the #govuk_check_boxes_fieldset
and
#govuk_check_box
helpers.
They’re required to ensure the both checkbox’s and hidden field’s
name
attribute is generated in the format that Rails
expects for a single field.
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 %>
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" autocomplete="off" />
<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>
Adding an option for ‘none of the above’
Sometimes none of the checkbox options apply, but leaving them all blank isn’t always intuitive for users.
Checkboxes created with exclusive: true
have special
behaviour that:
- unchecks all other checkboxes in the fieldset when they are checked
- unchecks them when any other checkboxes in the fieldset are checked
It usually makes sense to separate exclusive checkboxes from the others with a divider.
Input
= f.govuk_check_boxes_fieldset :countries, legend: { text: "Will you be travelling to any of these countries?", size: "m" } do
= f.govuk_check_box :countries,
:france,
label: { text: "France" },
link_errors: true
= f.govuk_check_box :countries,
:portugal,
label: { text: "Portugal" }
= f.govuk_check_box :countries,
:spain,
label: { text: "Spain" }
= f.govuk_check_box_divider
= f.govuk_check_box :countries,
:none,
exclusive: true,
label: { text: "No, I will not be travelling to any of these countries " }
<%= f.govuk_check_boxes_fieldset :countries, legend: { text: "Will you be travelling to any of these countries?", size: "m" } do %>
<%= f.govuk_check_box :countries, :france, label: { text: "France" }, link_errors: true %>
<%= f.govuk_check_box :countries, :portugal, label: { text: "Portugal" } %>
<%= f.govuk_check_box :countries, :spain, label: { text: "Spain" } %>
<%= f.govuk_check_box_divider %>
<%= f.govuk_check_box :countries, :none, exclusive: true, label: { text: "No, I will not be travelling to any of these countries " } %>
<% end %>
Output
<div class="govuk-form-group">
<fieldset class="govuk-fieldset">
<legend class="govuk-fieldset__legend govuk-fieldset__legend--m">
Will you be travelling to any of these countries?
</legend>
<input value="" name="person[countries][]" autocomplete="off" type="hidden" id="person_countries" />
<div class="govuk-checkboxes" data-module="govuk-checkboxes">
<div class="govuk-checkboxes__item">
<input id="person-countries-france-field" class="govuk-checkboxes__input" type="checkbox" value="france" name="person[countries][]" />
<label for="person-countries-france-field" class="govuk-label govuk-checkboxes__label">
France
</label>
</div>
<div class="govuk-checkboxes__item">
<input id="person-countries-portugal-field" class="govuk-checkboxes__input" type="checkbox" value="portugal" name="person[countries][]" />
<label for="person-countries-portugal-field" class="govuk-label govuk-checkboxes__label">
Portugal
</label>
</div>
<div class="govuk-checkboxes__item">
<input id="person-countries-spain-field" class="govuk-checkboxes__input" type="checkbox" value="spain" name="person[countries][]" />
<label for="person-countries-spain-field" class="govuk-label govuk-checkboxes__label">
Spain
</label>
</div>
<div class="govuk-checkboxes__divider">
or
</div>
<div class="govuk-checkboxes__item">
<input id="person-countries-none-field" class="govuk-checkboxes__input" data-behaviour="exclusive" type="checkbox" value="none" name="person[countries][]" />
<label for="person-countries-none-field" class="govuk-label govuk-checkboxes__label">
No, I will not be travelling to any of these countries
</label>
</div>
</div>
</fieldset>
</div>