> ## Documentation Index
> Fetch the complete documentation index at: https://docs.terminus.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Dropdown field

> A user-entered field whose value is chosen from a picklist, with single or multi-select, conditional picklists, and cascading selections.

<Info>
  A **dropdown** lets a submitter pick from a controlled list of values. The list comes from a [picklist](/reference/picklists) you point the field at with `picklist_id`. The field stores the option **code**; the picklist owns the options themselves.
</Info>

## When to use it

Use a dropdown when the valid values are a bounded, governed vocabulary that you want to control centrally:

* Channels, mediums, regions, product lines, business units.
* Any value you want consistent across every record so reports group cleanly.
* Selections that should narrow based on an earlier choice (a [cascade](/recipes/cascading-dropdowns)).

<Warning>
  Don't use a dropdown for free-form text. If submitters need to type an open value, use a [Text](/reference/fields/text) field instead.
</Warning>

The list of options lives on a picklist, not on the field. Three picklist types feed a dropdown:

<CardGroup cols={3}>
  <Card title="Static" icon="list" href="/reference/picklists/static">
    A hand-authored list. Flat or hierarchical.
  </Card>

  <Card title="Hierarchical" icon="network" href="/reference/picklists/hierarchical">
    Parent-to-child options for cascading dropdowns.
  </Card>

  <Card title="Automated" icon="refresh-cw" href="/reference/picklists/automated">
    Options derived live from another taxonomy's records.
  </Card>
</CardGroup>

## Settings reference

You set these on the field. `picklist_id` is required; everything else is optional.

| Setting          | Default  | What it does                                                                                                                                                                         |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `picklist_id`    | required | The picklist that supplies this dropdown's options.                                                                                                                                  |
| `picklist_rules` | none     | Conditional rules that swap in a different picklist based on other field values. First match wins; falls back to `picklist_id`. See [Conditional picklists](#conditional-picklists). |
| `multiple`       | `false`  | Allow more than one selection. Only for static, flat picklists.                                                                                                                      |
| `min_choices`    | none     | Smallest number of selections allowed (only when `multiple` is on).                                                                                                                  |
| `max_choices`    | none     | Largest number of selections allowed (only when `multiple` is on).                                                                                                                   |
| `separator`      | `,`      | Character that joins multiple selections in the stored value (only when `multiple` is on).                                                                                           |
| `default_value`  | none     | An option code to preselect, or an array of codes when `multiple` is on.                                                                                                             |
| `depends_on`     | none     | Makes this a cascading child of another dropdown. See [Cascading dropdowns](/recipes/cascading-dropdowns).                                                                           |

The `required` toggle lives on the field itself, not in these settings. Whether submitters can **add** values that aren't in the list is a property of the picklist (`allow_additions`), not the field. See [Letting submitters add options](/recipes/user-addable-options).

### Single vs. multiple

By default a dropdown takes one value. Turn on `multiple` to let submitters pick several. When multiple is on:

* `min_choices` and `max_choices` bound how many they may select. Leave either blank for no bound.
* The selected codes are joined with `separator` (a comma by default) when the value is stored.
* `default_value` becomes a list of codes rather than a single code.

Multi-select works only with **static, flat** picklists. It is not available on hierarchical or automated picklists, or on any dropdown that sets `depends_on`.

### Conditional picklists

Sometimes the right list of options depends on what was entered elsewhere. Add one or more **picklist rules** to the field: each rule says "when this condition holds, use this picklist instead." Terminus Hub evaluates the rules top to bottom and uses the first one that matches. If none match, it falls back to the field's default `picklist_id`.

For example, a `sub_channel` dropdown could show a "Paid sub-channels" list when `channel` is `paid`, and a "Organic sub-channels" list otherwise. You build these in the field's settings under **Picklist Rules**; reorder them to control precedence.

## Example

In the Campaign URL Builder, `utm_medium` is a single-select dropdown over a static picklist of mediums (`email`, `social`, `cpc`):

```yaml theme={null}
name: utm_medium
type: dropdown
required: true
settings:
  picklist_id: utm_mediums
  default_value: email
```

A multi-select `audiences` dropdown that requires one to three picks looks like this:

```yaml theme={null}
name: audiences
type: dropdown
settings:
  picklist_id: audience_segments
  multiple: true
  min_choices: 1
  max_choices: 3
  separator: ","
```

When a submitter picks `prospects` and `existing`, the record stores `prospects,existing`.

## Gotchas

* **The dropdown stores the code, not the label.** Reports and links use the option code. Keep codes stable; rename an option's display label freely, but changing a code leaves existing records pointing at the old value.
* **Multi-select is narrow.** `multiple` is rejected on hierarchical picklists, automated picklists, and any field that uses `depends_on`.
* **Conditional rules and cascades both filter.** If a field has both `picklist_rules` and `depends_on`, both narrow the options at once, so an over-tight combination can leave a submitter with nothing to choose.
* **Adding new values is a picklist setting.** A dropdown can only accept submitter-proposed values when its picklist has `allow_additions` turned on. See [Letting submitters add options](/recipes/user-addable-options).

## Related

* [Picklists overview](/reference/picklists)
* [Static picklist](/reference/picklists/static)
* [Hierarchical picklist](/reference/picklists/hierarchical)
* [Automated picklist](/reference/picklists/automated)
* [Cascading dropdowns](/recipes/cascading-dropdowns)
* [Letting submitters add options](/recipes/user-addable-options)
* [Filter options per taxonomy](/recipes/filter-options-per-taxonomy)
* [Field reference overrides](/reference/field-reference-overrides)