Checkbox

On this page

A single checkbox allows a user to affirm a statement or condition. 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.

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)

Examples

Default

Open example in a new tab 
<form action="/" accept-charset="UTF-8" method="post">
  <div class="cads-form-field">
    <div class="cads-form-field__content">
      <div class="cads-form-group cads-form-group--checkbox cads-checkbox-single">
        <div class="cads-form-group__item"><input name="forms_checkbox[checkbox]" type="hidden" value="0" /><input class="cads-form-group__input" id="forms_checkbox_checkbox-input" aria-required="false" aria-invalid="false" type="checkbox" value="1" name="forms_checkbox[checkbox]" /><label class="cads-form-group__label" id="forms_checkbox_checkbox-label" for="forms_checkbox_checkbox-input">I agree to the terms and conditions</label></div>
      </div>
    </div>
  </div>
</form>

<% @model = Forms::Checkbox.valid_example %>
<%= form_with model: @model, url: "/" do |form| %>
  <%= form.cads_checkbox(:checkbox) %>
<% 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

You must agree to the terms and conditions

<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">
      <div class="cads-form-group cads-form-group--checkbox cads-checkbox-single">
        <p class="cads-form-field__error-message" id="forms_checkbox_checkbox_required-error">You must agree to the terms and conditions</p>
        <div class="cads-form-group__item"><input name="forms_checkbox[checkbox_required]" type="hidden" value="0" /><input class="cads-form-group__input" id="forms_checkbox_checkbox_required-input" aria-required="false" aria-invalid="true" aria-describedby="forms_checkbox_checkbox_required-error" type="checkbox" value="1" name="forms_checkbox[checkbox_required]" /><label class="cads-form-group__label" id="forms_checkbox_checkbox_required-label" for="forms_checkbox_checkbox_required-input">I agree to the terms and conditions</label></div>
      </div>
    </div>
  </div>
</form>

<% @model = Forms::Checkbox.invalid_example %>
<%= form_with model: @model, url: "/" do |form| %>
  <%= form.cads_checkbox(:checkbox_required) %>
<% end %>

Using with Rails

When using with Rails we recommend using the form builder method provided by CitizensAdviceComponents::FormBuilder.

cads_checkbox(attribute, options = {})

The method works similarly to the default checkbox helper.

<%= form_with model: @model, url: "/" do |form| %>
  <%= form.cads_checkbox(:example) %>
<% end %>

View component version

We also provide an older view component version of the component

<%= render CitizensAdviceComponents::CheckboxSingle.new(
  name: "a-single-checkbox"
) do |c| %>
  <% c.with_checkbox(
    label: "I agree to the 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