Skip to main content

DropdownRenamed in 5.0+, Improved in 5.17+

A select dropdown menu field. The field.type property value is dropdown (for conditionals).

​Settings

  • Can specify labels (with values assumed) or labels and values (that differ).
    • To make the first option empty, use labels and values approach with the first option having something like Please select... for the label, and leave option blank.
  • 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. Disabled by default.

​Styling & Customization

​Customize Searchable DropdownsNew in 5.17+

When Enable Search is enabled, Freeform enhances the Dropdown with a searchable control. Its appearance is derived from the original select's styles.

​Appearance

Wrap the field in a container such as .my-dropdown, then customize the generated control:

.my-dropdown .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-dropdown .ff-searchable__list {
  max-height: 12rem;
}

.my-dropdown .ff-searchable__option:not([aria-disabled="true"]):hover,
.my-dropdown .ff-searchable__option[data-active] {
  background: #4f46e5;
  color: #fff;
}

The CSS properties require !important because Freeform applies automatically derived theme values inline.

​Search labels

Default labels are translatable. Manually rendered selects can provide custom wording through the JSON configuration in data-freeform-searchable:

<div class="my-dropdown">
  <select
    name="country"
    data-freeform-searchable='{
      "enabled": true,
      "placeholder": "Search countries...",
      "noResults": "No matching countries.",
      "toggleLabel": "Show countries",
      "resultsLabel": "{count} countries available."
    }'
  >
    <option value="">Select a country</option>
    <option value="ca">Canada</option>
    <option value="us">United States</option>
  </select>
</div>

Keep {count} in the results message. The original select remains responsible for submitted values. 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