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

Open example in a new tab
Example checkbox group (optional)
<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,
    collection: @model.options,
    text_method: :name,
    value_method: :id
  ) %>
<% end %>

With hint

Use hint text for help that’s relevant to the majority of users, based on the needs of your service.

Open example in a new tab
Example checkbox group with hint (optional)

Example hint text

<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,
    collection: @model.options,
    text_method: :name,
    value_method: :id,
    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.

Open example in a new tab
Example checkbox group

Select an option

<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,
    collection: @model.options,
    text_method: :name,
    value_method: :id,
    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.

Open example in a new tab

Example checkbox group

<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,
    collection: @model.options,
    text_method: :name,
    value_method: :id,
    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 = {})

The method works similarly to the default collection_checkboxes helper.

<%= form_with model: @model, url: "/" do |form| %>
  <%= form.cads_collection_checkboxes(
    :example,
    collection: [
      ["option_1", "Option 1"],
      ["option_2", "Option 2"],
      ["option_3", "Option 3"],
      ["option_4", "Option 4"],
      ["option_5", "Option 5"],
    ],
    text_method: :first,
    value_method: :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,
    collection: Locations.all,
    text_method: :id,
    value_method: :name,
    hint: "Example hint text"
  ) %>
<% end %>

The :value_method and :text_method parameters are methods to be called on each member of collection. The return values are used as the value attribute and contents of each checkbox.

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>

View component version

We also provide an older view component version of the component

<%= render CitizensAdviceComponents::CheckboxGroup.new(
  legend: "This is the group legend",
  name: "my-checkbox-group"
) do |c|
  c.with_inputs([
    { label: "Option 1", value: 1, checked: true },
    { label: "Option 2", value: 2 },
    { label: "Option 3", value: 3 }
  ])
end %>
Component arguments
Argument Description
Argument name Description Required, field name
Argument id Description Optional, allows customising the id. By default the id is autogenerated based on the name
Argument legend Description Required, the text for the fieldset legend associated with the inputs
Argument options Description Optional, a hash with one or more of the following values:
Argument options[:hint] Description → Optional, hint text for the input
Argument options[:error_message] Description → Optional, an error message for the input
Argument options[:optional] Description → Optional, boolean indicating the field is optional (ie not required)
Argument options[:page_heading] Description → Optional, boolean indicating the field label is a page heading