City of Ghent Style Guide

Checkboxes

When to use this component

Use the checkboxes component to help users:

  • Toggle a single option on or off.
  • Select one or more options from a fixed, short list of options.

When not to use this component

Do not use the checkboxes component when you need to help users select one or more options from a long list of options. In this case, use checkboxes dynamic component instead.

Do not use the checkboxes component when users should only be able to select one option and no more. In this case, use the radios component instead.

How it works

  • Checkboxes are grouped in a fieldset.
  • The fieldset uses a legend to present a description for the checkboxes. This is typically a question.
  • Users should be able to select one or more options.
  • Do not select checkboxes by default as users might not notice this, resulting in not realising they missed a question and/or sending a wrong answer.
  • The options should have short but clearly different labels. There’s no need to name the action “Select this checkbox to…” because it is already a checkbox. Avoid repeating words at the start of the labels for the options so that the options are easiliy scannable.

Usage, behavior, layout and validation

The checkboxes component is a form element that should always be used in a form. For a description of the usage, the behavior, the layout and validation of form elements, see the form component examples and documentation.

Checkboxes: Default 

<fieldset class="form-item {{ modifier }}">
  <legend>
    <span class="legend-title">{{ label }}</span>
    {% if label_optional %}
      <span class="label-optional">({{ label_optional }})</span>
    {% endif %}
  </legend>
  <div class="form-item">
    {% if field_description %}
      {% include '@field-message' with {
        "field_message": field_description,
        "id": id ~ '-description',
        "modifier": null
      } %}
    {% endif %}
    <div class="form-columns">
      <div class="form-item-column">
        {% for option in options %}
          {% include '@input' with {
            "id": "input-" ~ id ~ "-" ~ modifier ~ "-" ~ option.id,
            "type": 'checkbox',
            "name": option.name,
            "label": option.label,
            "modifier": modifier,
            "value": option.value,
            "attributes": option.attributes
          } %}
        {% endfor %}
      </div>

      {% apply spaceless %}
      <div class="form-item-column">
        {% if modifier == 'error' %}
          {% include '@field-message' with {
            "id": id ~ '-validation',
            "modifier": "error"
          } %}
        {% endif %}

        {% if modifier == 'success' %}
          {% include '@field-message' with {
            "id": id ~ '-validation',
            "modifier": "success"
          } %}
        {% endif %}
      </div>
      {% endapply %}
    </div>
  </div>
</fieldset>
 
<fieldset class="form-item ">
    <legend>
        <span class="legend-title">Checkboxes</span>
    </legend>
    <div class="form-item">
        <div class="form-columns">
            <div class="form-item-column">
                <div class="checkbox">

                    <input type="checkbox" id="input-input-checkbox--checkbox-error-1" name="checkboxgroup-error" class="checkbox" />
                    <label for="input-input-checkbox--checkbox-error-1">checkbox option 1</label>
                </div>
                <div class="checkbox">

                    <input type="checkbox" id="input-input-checkbox--checkbox-error-2" checked="checked" name="checkboxgroup-error" class="checkbox" />
                    <label for="input-input-checkbox--checkbox-error-2">checkbox option 2</label>
                </div>
            </div>

            <div class="form-item-column"></div>
        </div>
    </div>
</fieldset>
 
{
  "id": "input-checkbox",
  "label": "Checkboxes",
  "options": [
    {
      "label": "checkbox option 1",
      "name": "checkboxgroup-error",
      "id": "checkbox-error-1"
    },
    {
      "label": "checkbox option 2",
      "name": "checkboxgroup-error",
      "id": "checkbox-error-2",
      "attributes": "checked=\"checked\""
    }
  ]
}