Checkbox group
On this page
A checkbox group allows a user to select one or more options from a list of choices. Use a checkbox group when a user can select one or more options from a list of choices.
Do not use a checkbox group if:
- the user should only be able to select one choice from a list of options (use a radio group for this)
- there is only one checkbox in the list of options, for example agreeing to terms and conditions (use checkbox for this)
Examples
Default
<form action="/" accept-charset="UTF-8" method="post">
<div class="cads-form-field">
<div class="cads-form-field__content">
<fieldset class="cads-form-group cads-form-group--checkbox"><legend class="cads-form-field__label">Example checkbox group <span class="cads-form-field__optional">(optional)</span></legend><input type="hidden" name="forms_checkbox_group[checkbox_group][]" value="" />
<div class="cads-form-group__item"><input class="cads-form-group__input" id="forms_checkbox_group_checkbox_group-input" type="checkbox" value="option_1" name="forms_checkbox_group[checkbox_group][]" /><label class="cads-form-group__label" for="forms_checkbox_group_checkbox_group-input">Option 1</label></div>
<div class="cads-form-group__item"><input class="cads-form-group__input" id="forms_checkbox_group_checkbox_group-1" type="checkbox" value="option_2" name="forms_checkbox_group[checkbox_group][]" /><label class="cads-form-group__label" for="forms_checkbox_group_checkbox_group-1">Option 2</label></div>
<div class="cads-form-group__item"><input class="cads-form-group__input" id="forms_checkbox_group_checkbox_group-2" type="checkbox" value="option_3" name="forms_checkbox_group[checkbox_group][]" /><label class="cads-form-group__label" for="forms_checkbox_group_checkbox_group-2">Option 3</label></div>
</fieldset>
</div>
</div>
</form>
<% @model = Forms::CheckboxGroup.valid_example %>
<%= form_with model: @model, url: "/" do |form| %>
<%= form.cads_collection_checkboxes(
:checkbox_group,
@model.options,
:id,
:name
) %>
<% end %>
With hint
Use hint text for help that’s relevant to the majority of users, based on the needs of your service.
<form action="/" accept-charset="UTF-8" method="post">
<div class="cads-form-field">
<div class="cads-form-field__content">
<fieldset class="cads-form-group cads-form-group--checkbox" aria-describedby="forms_checkbox_group_checkbox_group_hint-hint"><legend class="cads-form-field__label">Example checkbox group with hint <span class="cads-form-field__optional">(optional)</span></legend>
<p class="cads-form-field__hint" id="forms_checkbox_group_checkbox_group_hint-hint">Example hint text</p>
<input type="hidden" name="forms_checkbox_group[checkbox_group_hint][]" value="" />
<div class="cads-form-group__item"><input class="cads-form-group__input" id="forms_checkbox_group_checkbox_group_hint-input" type="checkbox" value="option_1" name="forms_checkbox_group[checkbox_group_hint][]" /><label class="cads-form-group__label" for="forms_checkbox_group_checkbox_group_hint-input">Option 1</label></div>
<div class="cads-form-group__item"><input class="cads-form-group__input" id="forms_checkbox_group_checkbox_group_hint-1" type="checkbox" value="option_2" name="forms_checkbox_group[checkbox_group_hint][]" /><label class="cads-form-group__label" for="forms_checkbox_group_checkbox_group_hint-1">Option 2</label></div>
<div class="cads-form-group__item"><input class="cads-form-group__input" id="forms_checkbox_group_checkbox_group_hint-2" type="checkbox" value="option_3" name="forms_checkbox_group[checkbox_group_hint][]" /><label class="cads-form-group__label" for="forms_checkbox_group_checkbox_group_hint-2">Option 3</label></div>
</fieldset>
</div>
</div>
</form>
<% @model = Forms::CheckboxGroup.valid_example %>
<%= form_with model: @model, url: "/" do |form| %>
<%= form.cads_collection_checkboxes(
:checkbox_group_hint,
@model.options,
:id,
:name,
hint: "Example hint text"
) %>
<% end %>
With error message
Error messages are used to highlight where users need to change information. They’re used together with an error summary.
<form action="/" accept-charset="UTF-8" method="post">
<div class="cads-form-field cads-form-field--has-error">
<div class="cads-form-field__error-marker"></div>
<div class="cads-form-field__content">
<fieldset class="cads-form-group cads-form-group--checkbox" aria-describedby="forms_checkbox_group_checkbox_group_required-error"><legend class="cads-form-field__label">Example checkbox group </legend>
<p class="cads-form-field__error-message" id="forms_checkbox_group_checkbox_group_required-error">Select an option</p>
<input type="hidden" name="forms_checkbox_group[checkbox_group_required][]" value="" />
<div class="cads-form-group__item"><input class="cads-form-group__input" id="forms_checkbox_group_checkbox_group_required-input" type="checkbox" value="option_1" name="forms_checkbox_group[checkbox_group_required][]" /><label class="cads-form-group__label" for="forms_checkbox_group_checkbox_group_required-input">Option 1</label></div>
<div class="cads-form-group__item"><input class="cads-form-group__input" id="forms_checkbox_group_checkbox_group_required-1" type="checkbox" value="option_2" name="forms_checkbox_group[checkbox_group_required][]" /><label class="cads-form-group__label" for="forms_checkbox_group_checkbox_group_required-1">Option 2</label></div>
<div class="cads-form-group__item"><input class="cads-form-group__input" id="forms_checkbox_group_checkbox_group_required-2" type="checkbox" value="option_3" name="forms_checkbox_group[checkbox_group_required][]" /><label class="cads-form-group__label" for="forms_checkbox_group_checkbox_group_required-2">Option 3</label></div>
</fieldset>
</div>
</div>
</form>
<% @model = Forms::CheckboxGroup.invalid_example %>
<%= form_with model: @model, url: "/" do |form| %>
<%= form.cads_collection_checkboxes(
:checkbox_group_required,
@model.options,
:id,
:name,
required: true
) %>
<% end %>
Page heading
Used for one question per page forms. Using similar approach to the one described in gov.uk - Making labels and legends headings.
<form action="/" accept-charset="UTF-8" method="post">
<div class="cads-form-field">
<div class="cads-form-field__content">
<fieldset class="cads-form-group cads-form-group--checkbox"><legend class="cads-form-field__label">
<h1 class="cads-page-title">Example checkbox group</h1>
</legend><input type="hidden" name="forms_checkbox_group[checkbox_group][]" value="" />
<div class="cads-form-group__item"><input class="cads-form-group__input" id="forms_checkbox_group_checkbox_group-input" type="checkbox" value="option_1" name="forms_checkbox_group[checkbox_group][]" /><label class="cads-form-group__label" for="forms_checkbox_group_checkbox_group-input">Option 1</label></div>
<div class="cads-form-group__item"><input class="cads-form-group__input" id="forms_checkbox_group_checkbox_group-1" type="checkbox" value="option_2" name="forms_checkbox_group[checkbox_group][]" /><label class="cads-form-group__label" for="forms_checkbox_group_checkbox_group-1">Option 2</label></div>
<div class="cads-form-group__item"><input class="cads-form-group__input" id="forms_checkbox_group_checkbox_group-2" type="checkbox" value="option_3" name="forms_checkbox_group[checkbox_group][]" /><label class="cads-form-group__label" for="forms_checkbox_group_checkbox_group-2">Option 3</label></div>
</fieldset>
</div>
</div>
</form>
<% @model = Forms::CheckboxGroup.valid_example %>
<%= form_with model: @model, url: "/" do |form| %>
<%= form.cads_collection_checkboxes(
:checkbox_group,
@model.options,
:id,
:name,
page_heading: true
) %>
<% end %>
Implementation
You must always have a label associated with the input element.
The components we provide use wrap checkbox groups in a fieldset. In this context the ‘label’ is typically the fieldset legend, as every checkbox option is a label + input in its own right.
Using with Rails
When using with Rails we recommend using the form builder method provided by CitizensAdviceComponents::FormBuilder.
cads_collection_checkboxes(attribute, collection, value_method, text_method, options = {}, html_options = {})
The method works similarly to the default collection_checkboxes helper.
<%= form_with model: @model, url: "/" do |form| %>
<%= form.cads_collection_checkboxes(
:example,
[
["option_1", "Option 1"],
["option_2", "Option 2"],
["option_3", "Option 3"],
["option_4", "Option 4"],
["option_5", "Option 5"],
],
:first,
:last,
hint: "Example hint text",
required: true
) %>
<% end %>
But this can also work with any collection:
<%= form_with model: @model, url: "/" do |form| %>
<%= form.cads_collection_checkboxes(
:example,
Locations.all,
:id,
:name,
hint: "Example hint text"
) %>
<% end %>
The method accepts an options hash with the following optional parameters:
:label- The text for the label associated with the input. Defaults to using translations.:hint- Hint text for the input:required- Boolean indicating the field is optional (i.e. not required):page_heading- Wraps the<legend>in a<h1>
Questions and contributions
For National Citizens Advice staff you can find us in the #design-system channel on Slack. For open issues, roadmap, and source code see the GitHub project.