Skip to main content

Multiple SelectImproved in 5.17+

A multiple-select field. The field.type property value is multiple-select (for conditionals).

​Settings

  • Can specify labels (with values assumed) or labels and values (that differ).
  • Supports <optgroup>'s. To use this, enable the toggle under the Optgroup column for the applicable row.New in 5.13+
  • Can be automatically populated with select Craft Elements or Pre-defined list options.
  • Can be used as a User Select email notification.
  • Enable SearchNew in 5.17+
    • Lets visitors filter the available options by typing, making longer lists easier to navigate. Selected options become tags above the input. Disabled by default.

​Styling & Customization

​Customize Searchable Multiple SelectsNew in 5.17+

When Enable Search is enabled, selected options appear as removable pills above the search input.

​Appearance

Wrap the field in a container such as .my-multiple-select, then customize its colors and selected-option pills:

.my-multiple-select .ff-searchable {
  --ff-searchable-bg: #fff !important;
  --ff-searchable-menu-bg: #fff !important;
  --ff-searchable-color: #1f2937 !important;
  --ff-searchable-border: #d1d5db !important;
  --ff-searchable-radius: 6px !important;
}

.my-multiple-select .ff-searchable__pills {
  gap: 0.5rem;
}

.my-multiple-select .ff-searchable button.ff-searchable__remove {
  background: #eef2ff;
  color: #4338ca;
  border-color: #c7d2fe;
  border-radius: 999px;
}

.my-multiple-select .ff-searchable__list {
  max-height: 12rem;
}

The CSS properties require !important to override Freeform's automatically derived theme values.

​Search and Removal Labels

Default labels are translatable. Manually rendered selects can provide custom wording:

<div class="my-multiple-select">
  <select
    name="interests[]"
    multiple
    data-freeform-searchable='{
      "enabled": true,
      "placeholder": "Search interests...",
      "noResults": "No matching interests.",
      "removeLabel": "Remove {label}",
      "toggleLabel": "Show interests",
      "resultsLabel": "{count} interests available."
    }'
  >
    <option value="design">Design</option>
    <option value="development">Development</option>
    <option value="marketing">Marketing</option>
  </select>
</div>

Keep {label} in the removal label and {count} in the results message. Preserve the multiple attribute and the field's expected input name. Custom templates must load Freeform's JavaScript and searchable-select styles.

​Templating

PropertyDescription
field.enableSearchWhether Enable Search is enabled for the field.
field.searchableConfigThe search configuration, including its enabled state and translated interface labels.

The searchableConfig object contains:

KeyDescription
enabledWhether the searchable control is enabled.
placeholderPlaceholder text for the search input.
noResultsMessage displayed when no options match.
toggleLabelAccessible label for the button that opens the options.
resultsLabelResults announcement containing the {count} placeholder.
removeLabelLabel for removing a selected option in Multiple Select fields, containing the {label} placeholder.

Use field.render() or field.renderInput() to generate the data-freeform-searchable configuration automatically when search is enabled.

The underlying select remains responsible for submitted values. When manually rendering a Multiple Select field, preserve its multiple attribute and array-style input name.

​Resources

Page Feedback