> ## 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.

# Letting submitters add options

> Let submitters propose new dropdown values inline, promoted to real picklist options only when the submission is approved.

<Info>
  **Goal:** let a submitter type a value that is not in the dropdown yet, without waiting on an admin. The proposed value rides along with their submission and becomes a real picklist option only when the submission is approved.
</Info>

## What you'll build

A static picklist with **Allow new values** turned on (`allow_additions: true`), so a [dropdown field](/reference/fields/dropdown) backed by it lets submitters propose values inline. This works for flat and hierarchical static lists. It does not apply to [automated picklists](/reference/picklists/automated), whose options come from records. The example uses the `UTM Sources` list from the Campaign URL Builder.

## Prerequisites

* A governance model you can edit and permission to publish it.
* A static picklist that a dropdown field points at.

## Steps

<Steps>
  <Step title="Turn on Allow new values">
    Open your governance model, go to **Picklists**, and open the **UTM Sources** static list (or create one). Turn on **Allow new values** and save. This sets `allow_additions: true` on the picklist. Every dropdown field backed by this list now lets submitters add values; there is no per-field toggle.
  </Step>

  <Step title="Point a dropdown field at the picklist">
    In **Fields**, open the `utm_source` dropdown field and confirm its picklist is `UTM Sources`. The field inherits the picklist's setting, so nothing else is needed on the field.
  </Step>

  <Step title="Publish the governance model">
    Publish so the change is part of the version submitters fill against. Approval checks the published version, not the live toggle, so a value can only be added when the version the submission was filled against allowed additions.
  </Step>

  <Step title="Submit and propose a new value">
    Open a taxonomy that includes `utm_source` and start a submission. Open the `utm_source` dropdown, type a value that is not in the list (for example `partnerstack`), and pick the **Add new** choice that appears. The proposed value attaches to that submission row, marked as a new value with a badge.
  </Step>

  <Step title="Approve to promote, or reject to discard">
    Submit for review. A reviewer sees the row with a clear marker that the value is new and not yet in the list. On **approval**, the proposed value is added to the picklist as a real option and is available to every future submission on every taxonomy that uses the list. On rejection or cancellation, the proposed value disappears with the submission and the picklist is unchanged.
  </Step>
</Steps>

## What the submitter sees

While filling the form, when the typed value is not already an option, the dropdown offers an **Add new** item at the bottom of the list. Once selected, the value shows on the row with a "new" badge so it is clear this is a proposal, not yet an established option. The new value lives on that submission only. Other submitters do not see it until it is approved into the list.

If an option that was selected earlier has since been removed from the picklist, the builder marks it with a "deleted" badge so the submitter knows to repick.

## Worked example

A `UTM Sources` static list with additions enabled, and the field that uses it:

```yaml theme={null}
- id: utm_sources
  name: UTM Sources
  type: static
  allow_additions: true
  options:
    - { code: newsletter, description: Newsletter }
    - { code: facebook,   description: Facebook }
    - { code: google,     description: Google }

- name: utm_source
  type: dropdown
  required: true
  settings: { picklist_id: utm_sources }
```

A submitter filling a campaign can pick `Facebook`, or type `reddit` and pick **Add new**. The submission stores `reddit` as a new value on that row. When the submission is approved, `reddit` becomes a regular option on `UTM Sources`, available to everyone from then on. If the submission is rejected, `reddit` is discarded with it.

## Verify

* Before approval, open **Picklists** then **UTM Sources**. The proposed value is not in the options list yet.
* After approval, reopen **UTM Sources**. The new value is now a regular option, available on every taxonomy that uses this list.
* A proposed value on a rejected submission never appears in the picklist.

## Gotchas

* **New values are added on approval, gated by the published version.** A proposed value becomes a real option only when its submission is approved, and only if the version the submission was filled against allowed additions. Turning the switch on after a submission was started does not retroactively let that submission add values.
* **Rejected submissions do not add values.** If a reviewer rejects a submission that proposed `newsleter` (a typo), the proposal is discarded with the submission. It does not linger in the picklist.
* **Reviewers should spot-check proposed values.** Nothing stops a submitter from typing `Newsletter` with a capital N next to an existing `newsletter`, or coining a near-duplicate. Scanning proposed values for typos and case inconsistencies is part of the review step.
* **Allow new values is static-only.** It applies to flat and hierarchical static picklists. It does not apply to [automated picklists](/reference/picklists/automated), whose options come from another taxonomy's records, so the toggle is not shown there.
* **An empty list is fine when additions are on.** A static picklist normally needs at least one option, but with **Allow new values** on it can ship empty and let submitters populate it.
* **A value proposed under a parent inherits that parent.** On a hierarchical list, a proposed value carries the ancestry of whatever the submitter chose in the parent dropdown, with no extra work.

## Related

* [Static picklist](/reference/picklists/static): where **Allow new values** lives.
* [Hierarchical picklist](/reference/picklists/hierarchical): additions under a parent option.
* [Dropdown field](/reference/fields/dropdown): the field that surfaces the option list.
* [Review and approve submissions](/guides/review-and-approve-submissions): where proposed values are promoted.
* [Tutorial Part 6: User-addable picklists](/tutorial/06-user-addable-picklists)