Multi-select Fields

Multi-select fields give you an input where multiple items may be selected.

# Settings

Multi-select fields have the following settings:

Multi-select Options – Define the options that will be available in the field. You even get to set the option values and labels separately, and choose which ones should be selected by default.

# Development

# Querying Elements with Multi-select Fields

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

Possible values include:

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

Twig
PHP

{# Fetch entries with the 'foo' option selected #}
{% set entries = craft.entries()
  .myFieldHandle('foo')
  .all() %}

# Working with Multi-select Field Data

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

Twig
PHP

{% set value = entry.myFieldHandle %}

That will give you a craft\fields\data\MultiOptionsFieldData (opens new window) object that contains the field data.

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

Twig
PHP

{% for option in entry.myFieldHandle %}
  Label: {{ option.label }}
  Value: {{ option }} or {{ option.value }}
{% endfor %}

To loop through all the available options, iterate over the options (opens new window) property:

Twig
PHP

{% for option in entry.myFieldHandle.options %}
  Label:    {{ option.label }}
  Value:    {{ option }} or {{ option.value }}
  Selected: {{ option.selected ? 'Yes' : 'No' }}
{% endfor %}

To see if any options are selected, use the length (opens new window) filter:

Twig
PHP

{% if entry.myFieldHandle|length %}

To see if a particular option is selected, use contains() (opens new window)

Twig
PHP

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

# Saving Multi-select Fields

If you have an element form, such as an entry form (opens new window), that needs to contain a multi-select 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 options are selected. #}
{{ hiddenInput('fields[myFieldHandle]', '') }}

<select multiple name="fields[myFieldHandle][]">
  {% for option in field.options %}
      {% set selected = entry is defined
        ? entry.myFieldHandle.contains(option.value)
        : option.default %}

      <option value="{{ option.value }}"
        {% if selected %} selected{% endif %}
      >
        {{ option.label }}
      </option>
  {% endfor %}
</select>