Alpha

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

Checkbox

On this page

A single checkbox allows a user to affirm a statement or condition.

Open example in a new tab 
<div class="cads-form-field">
  <div class="cads-form-group cads-form-field__content cads-form-group--checkbox cads-checkbox-single">
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="a-single-checkbox-0" name="a-single-checkbox" value="agreed-to-tcs">
      <label class="cads-form-group__label"
             for="a-single-checkbox-0">
        I agree to the great terms and conditions
      </label>
    </div>
  </div>
</div>
<%= render CitizensAdviceComponents::CheckboxSingle.new(name: "a-single-checkbox") do |c|
  c.with_checkbox(label: "I agree to the great terms and conditions", value: "agreed-to-tcs")
end %>

When to use

Use a single checkbox when you want a user to confirm they have understood or agree to something. For example, showing the have read and understood some terms and conditions.

When not to use

Do not use a checkbox if the user:

  • should be able to select one or more choices from a list of options (use a checkbox group for this)
  • should only be able to select one choice from a list of options (use a radio group for this)

How it works

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

Agree to the terms and conditions 

<div class="cads-form-field cads-form-field--has-error">
  <div class="cads-form-field__error-marker"></div>
  <div class="cads-form-group cads-form-field__content cads-form-group--checkbox cads-checkbox-single">
    <p class="cads-form-field__error-message" id="a-single-checkbox-error-error">
      Agree to the terms and conditions
    </p>
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="a-single-checkbox-error-0" name="a-single-checkbox-error" value="agreed-to-tcs-error" aria-describedby="a-single-checkbox-error-error" aria-invalid="true">
      <label class="cads-form-group__label"
             for="a-single-checkbox-error-0">
        I agree to the great terms and conditions
      </label>
    </div>
  </div>
</div>
<%= render CitizensAdviceComponents::CheckboxSingle.new(name: "a-single-checkbox-error", error_message: "Agree to the terms and conditions") do |c|
  c.with_checkbox(label: "I agree to the great terms and conditions", value: "agreed-to-tcs-error")
end %>

With custom id

By default, the checkbox id is generated based on the name. If the name and the id need to use a different naming convention, a custom id can be passed.

Open example in a new tab 
<div class="cads-form-field">
  <div class="cads-form-group cads-form-field__content cads-form-group--checkbox cads-checkbox-single">
    <div class="cads-form-group__item">
      <input class="cads-form-group__input" type="checkbox" id="test-id" name="a-single-checkbox[test]" value="agreed-to-tcs">
      <label class="cads-form-group__label"
             for="test-id">
        I agree to the great terms and conditions
      </label>
    </div>
  </div>
</div>
<%= render CitizensAdviceComponents::CheckboxSingle.new(name: "a-single-checkbox[test]") do |c|
  c.with_checkbox(label: "I agree to the great terms and conditions", value: "agreed-to-tcs", id: "test-id")
end %>

Using with Rails

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

<%= render CitizensAdviceComponents::CheckboxSingle.new(name: "a-single-checkbox") do |c|
  c.with_checkbox(label: "I agree to the great terms and conditions", value: "agreed-to-tcs")
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 error_message Description Optional, an error message for the input