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 

<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>
 
<!-- Default -->
<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>


<!-- With Error -->
<fieldset class="form-item error">
    <legend>
        <span class="legend-title">input-checkbox</span>
    </legend>
    <div class="form-item">
        <div class="field-message " id="input-checkbox--error-description">
            You can add an optional field description here.
            <div class="accolade "></div>
        </div>
        <div class="form-columns">
            <div class="form-item-column">
                <div class="checkbox">

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

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

            <div class="form-item-column">
                <div class="field-message error" role="alert" id="input-checkbox--error-validation">
                    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec laoreet, urna sit amet convallis rhoncus, felis ex.
                    <div class="accolade "></div>
                </div>
            </div>
        </div>
    </div>
</fieldset>


<!-- With Success -->
<fieldset class="form-item success">
    <legend>
        <span class="legend-title">input-text</span>
    </legend>
    <div class="form-item">
        <div class="field-message " id="input-checkbox--success-description">
            You can add an optional field description here.
            <div class="accolade "></div>
        </div>
        <div class="form-columns">
            <div class="form-item-column">
                <div class="checkbox">

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

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

            <div class="form-item-column">
                <div class="field-message success" role="alert" id="input-checkbox--success-validation">
                    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec laoreet, urna sit amet convallis rhoncus, felis ex.
                    <div class="accolade "></div>
                </div>
            </div>
        </div>
    </div>
</fieldset>


<!-- Disabled -->
<fieldset class="form-item disabled">
    <legend>
        <span class="legend-title">input-text</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--disabled-disabled-checkbox-error-1" name="checkboxgroup-error" class="checkbox disabled" disabled="disabled" />
                    <label for="input-input-checkbox--disabled-disabled-checkbox-error-1">checkbox option 1</label>
                </div>
                <div class="checkbox">

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

            <div class="form-item-column"></div>
        </div>
    </div>
</fieldset>


/* Default */
{
  "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\""
    }
  ]
}


/* With Error */
{
  "id": "input-checkbox--error",
  "label": "input-checkbox",
  "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\""
    }
  ],
  "modifier": "error",
  "field_description": "You can add an optional field description here.",
  "field_message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec laoreet, urna sit amet convallis rhoncus, felis ex."
}


/* With Success */
{
  "id": "input-checkbox--success",
  "label": "input-text",
  "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\""
    }
  ],
  "modifier": "success",
  "field_description": "You can add an optional field description here.",
  "field_message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec laoreet, urna sit amet convallis rhoncus, felis ex."
}


/* Disabled */
{
  "id": "input-checkbox--disabled",
  "label": "input-text",
  "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\""
    }
  ],
  "modifier": "disabled",
  "disabled": true,
  "field_message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec laoreet, urna sit amet convallis rhoncus, felis ex."
}