Checkboxes Fields

Checkboxes fields give you a group of checkboxes.

Settings

Checkboxes fields have the following settings:

  • Checkbox Options – Define the checkboxes that will be available in the field. You even get to set the option values and labels separately, and choose which ones should be checked by default.

Development

Querying Elements with Checkboxes Fields

When querying for elements that have a Checkboxes field, you can filter the results based on the Checkboxes field data using a query param named after your field’s handle.

Possible values include:

| Value | Fetches elements… | - | - | 'foo' | with a foo option checked. | 'not foo' | without a foo option checked. | ['foo', 'bar'] | with foo or bar options selected. | ['and', 'foo', 'bar'] | with foo and bar options selected.

{# Fetch entries with the 'foo' option checked #}
{% set entries = craft.entries()
  .myFieldHandle('foo')
  .all() %}
// Fetch entries with the 'foo' option checked
$entries = \craft\elements\Entry::find()
    ->myFieldHandle('foo')
    ->all();

Working with Checkboxes Field Data

If you have an element with a Checkboxes field in your template, you can access its data using your Checkboxes field’s handle:

{% set value = entry.myFieldHandle %}
$value = $entry->myFieldHandle %}

That will give you a craft3:craft\fields\data\MultiOptionsFieldData object that contains the field data.

To loop through all checked options, iterate over the field value:

{% for option in entry.myFieldHandle %}
  Label: {{ option.label }}
  Value: {{ option }} or {{ option.value }}
{% endfor %}
foreach ($entry->myFieldHandle as $option) {
    // label: $option->label
    // value: $option or $option->value
}

To loop through all available options, iterate over the options property:

{% for option in entry.myFieldHandle.options %}
  Label:   {{ option.label }}
  Value:   {{ option }} or {{ option.value }}
  Checked: {{ option.selected ? 'Yes' : 'No' }}
{% endfor %}
foreach ($entry->myFieldHandle->options as $option) {
    // label:   $option->label
    // value:   $option or $option->value
    // checked: $option->selected ? 'Yes' : 'No'
}

To see if any options are checked, use the length filter or count method:

{% if entry.myFieldHandle|length %}
if (count($entry->myFieldHandle)) {

To see if a particular option is checked, use contains()

{% if entry.myFieldHandle.contains('foo') %}
if ($entry->myFieldHandle->contains('foo')) {

Saving Checkboxes Fields

If you have an element form, such as an entry form, that needs to contain a Checkboxes field, you can use this template as a starting point:

{% set field = craft.app.fields.getFieldByHandle('myFieldHandle') %}

{# Include a hidden input first so Craft knows to update the
   existing value, if no checkboxes are checked. #}
{{ hiddenInput('fields[myFieldHandle]', '') }}

  {% for option in field.options %}
    {% set checked = entry is defined
      ? entry.myFieldHandle.contains(option.value)
      : option.default %}

    <li><label>
      <input type="checkbox"
        name="fields[myFieldHandle][]"
        value="{{ option.value }}"
        {% if checked %}checked{% endif %}>
      {{ option.label }}
    </label></li>
  {% endfor %}