Alpha

This is an alpha release of our documentation site. View the roadmap.

Checkbox group

On this page

A checkbox group allows a user to select one or more options from a list of choices.

Open example in a new tab
This is the group legend 
<div class="cads-form-field">
  <fieldset class="cads-form-field__content cads-form-group cads-form-group--checkbox">
    <legend class="cads-form-field__label">
      This is the group legend
    </legend>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="my-checkbox-group-0" name="my-checkbox-group" value="1" checked="checked">
      <label class="cads-form-group__label" for="my-checkbox-group-0">
        Option 1
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="my-checkbox-group-1" name="my-checkbox-group" value="2">
      <label class="cads-form-group__label" for="my-checkbox-group-1">
        Option 2
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="my-checkbox-group-2" name="my-checkbox-group" value="3">
      <label class="cads-form-group__label" for="my-checkbox-group-2">
        Option 3
      </label>
    </div>
  </fieldset>
</div>
<%= 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 %>

When to use

Use a checkbox group when a user can select one or more options from a list of choices.

When not to use

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)

How it works

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
This is the group legend

This is the hint text

<div class="cads-form-field">
  <fieldset class="cads-form-field__content cads-form-group cads-form-group--checkbox">
    <legend class="cads-form-field__label">
      This is the group legend
    </legend>
    <p class="cads-form-field__hint">This is the hint text</p>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="my-checbox-group-hint-0" name="my-checbox-group-hint" value="1" checked="checked">
      <label class="cads-form-group__label" for="my-checbox-group-hint-0">
        Option 1
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="my-checbox-group-hint-1" name="my-checbox-group-hint" value="2">
      <label class="cads-form-group__label" for="my-checbox-group-hint-1">
        Option 2
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="my-checbox-group-hint-2" name="my-checbox-group-hint" value="3">
      <label class="cads-form-group__label" for="my-checbox-group-hint-2">
        Option 3
      </label>
    </div>
  </fieldset>
</div>
<%= render CitizensAdviceComponents::CheckboxGroup.new(
  legend: "This is the group legend",
  name: "my-checbox-group-hint",
  options: {
    hint: "This is the hint text"
  }
) do |c|
  c.with_inputs([
    { label: "Option 1", value: 1, checked: true },
    { label: "Option 2", value: 2 },
    { label: "Option 3", value: 3 }
  ])
end %>

With optional field marker

If a selection is not required, use the optional marker.

Open example in a new tab
This is the group legend (optional) 
<div class="cads-form-field">
  <fieldset class="cads-form-field__content cads-form-group cads-form-group--checkbox">
    <legend class="cads-form-field__label">
      This is the group legend
      <span class="cads-form-field__optional">(optional)</span>
    </legend>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="my-checkbox-group-optional-0" name="my-checkbox-group-optional" value="1" checked="checked">
      <label class="cads-form-group__label" for="my-checkbox-group-optional-0">
        Option 1
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="my-checkbox-group-optional-1" name="my-checkbox-group-optional" value="2">
      <label class="cads-form-group__label" for="my-checkbox-group-optional-1">
        Option 2
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="my-checkbox-group-optional-2" name="my-checkbox-group-optional" value="3">
      <label class="cads-form-group__label" for="my-checkbox-group-optional-2">
        Option 3
      </label>
    </div>
  </fieldset>
</div>
<%= render CitizensAdviceComponents::CheckboxGroup.new(
  legend: "This is the group legend",
  name: "my-checkbox-group-optional",
  options: {
    optional: true
  }
) do |c|
  c.with_inputs([
    { label: "Option 1", value: 1, checked: true },
    { label: "Option 2", value: 2 },
    { label: "Option 3", value: 3 }
  ])
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
This is the group legend

Select an option

<div class="cads-form-field cads-form-field--has-error">
  <div class="cads-form-field__error-marker"></div>
  <fieldset class="cads-form-field__content cads-form-group cads-form-group--checkbox">
    <legend class="cads-form-field__label">
      This is the group legend
    </legend>
    <p class="cads-form-field__error-message"  id="my-checkbox-group-error-error">Select an option</p>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="my-checkbox-group-error-0" name="my-checkbox-group-error" value="1" checked="checked" aria-describedby="my-checkbox-group-error-error" aria-invalid="true">
      <label class="cads-form-group__label" for="my-checkbox-group-error-0">
        Option 1
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="my-checkbox-group-error-1" name="my-checkbox-group-error" value="2" aria-describedby="my-checkbox-group-error-error" aria-invalid="true">
      <label class="cads-form-group__label" for="my-checkbox-group-error-1">
        Option 2
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="my-checkbox-group-error-2" name="my-checkbox-group-error" value="3" aria-describedby="my-checkbox-group-error-error" aria-invalid="true">
      <label class="cads-form-group__label" for="my-checkbox-group-error-2">
        Option 3
      </label>
    </div>
  </fieldset>
</div>
<%= render CitizensAdviceComponents::CheckboxGroup.new(
  legend: "This is the group legend",
  name: "my-checkbox-group-error",
  options: {
    error_message: "Select an option"
  }
) do |c|
  c.with_inputs([
    { label: "Option 1", value: 1, checked: true },
    { label: "Option 2", value: 2 },
    { label: "Option 3", value: 3 }
  ])
end %>

Additional attributes (View component only)

Any additional key/value pairs (beyond label and value) in your checkbox button definition will be added to the input.

Open example in a new tab
This is the group legend 
<div class="cads-form-field">
  <fieldset class="cads-form-field__content cads-form-group cads-form-group--checkbox">
    <legend class="cads-form-field__label">
      This is the group legend
    </legend>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="my-checkbox-group-additional-0" name="my-checkbox-group-additional" value="1" data-testid="first-input">
      <label class="cads-form-group__label" for="my-checkbox-group-additional-0">
        Option 1
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="my-checkbox-group-additional-1" name="my-checkbox-group-additional" value="2" data-testid="second-input">
      <label class="cads-form-group__label" for="my-checkbox-group-additional-1">
        Option 2
      </label>
    </div>
  </fieldset>
</div>
<%= render CitizensAdviceComponents::CheckboxGroup.new(
  legend: "This is the group legend",
  name: "my-checkbox-group-additional"
) do |c|
  c.with_inputs([
    { label: "Option 1", value: "1", "data-testid": "first-input" },
    { label: "Option 2", value: "2", "data-testid": "second-input" }
  ])
end %>

Checkbox ids (View component only)

The id attribute for each input will be automatically generated for you by the view component. They will take the form of: [name]-[index], where [index] is the position of the checkbox in the array passed into c.with_inputs above. eg my-checkbox-0, my-checkbox-1, etc. It is also possible to have an id which is not generated by the name by passing an id attribute. In this case, the format will be [id]-[index].

Open example in a new tab
This is the group legend 
<div class="cads-form-field">
  <fieldset class="cads-form-field__content cads-form-group cads-form-group--checkbox">
    <legend class="cads-form-field__label">
      This is the group legend
    </legend>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="my-checkbox-group-test-0" name="my-checkbox-group[test][]" value="1">
      <label class="cads-form-group__label" for="my-checkbox-group-test-0">
        Option 1
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="my-checkbox-group-test-1" name="my-checkbox-group[test][]" value="2">
      <label class="cads-form-group__label" for="my-checkbox-group-test-1">
        Option 2
      </label>
    </div>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="my-checkbox-group-test-2" name="my-checkbox-group[test][]" value="3">
      <label class="cads-form-group__label" for="my-checkbox-group-test-2">
        Option 3
      </label>
    </div>
  </fieldset>
</div>
<%= render CitizensAdviceComponents::CheckboxGroup.new(
  legend: "This is the group legend",
  name: "my-checkbox-group[test][]",
  id: "my-checkbox-group-test"
) do |c|
  c.with_inputs([
    { label: "Option 1", value: 1 },
    { label: "Option 2", value: 2 },
    { label: "Option 3", value: 3 }
  ])
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

If you are using the citizens_advice_components gem, you can call the component from within a template using:

<%= 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 hint Description → Optional, hint text for the input
Argument error_message Description → Optional, an error message for the input
Argument optional Description → Optional, boolean indicating the field is optional (ie not required)