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

# Static picklist

> A hand-authored list of options (code plus label) stored on the governance model and referenced by one or more dropdown fields.

<Info>
  A static picklist is a hand-authored list of options that one or more [dropdown](/reference/fields/dropdown) fields point at. You type the values once, and every dropdown that references the list offers the same choices. It is the most common kind of picklist, and the building block for [hierarchical](/reference/picklists/hierarchical) lists too.
</Info>

## When to use it

* You own a bounded vocabulary: goals, regions, product lines, priorities, UTM mediums.
* The values change rarely, or any change should be reviewed before it ships.
* You want to attach a readable label to each stored value, not just a raw list of strings.

<Warning>
  Do not use a static picklist when the options already live as approved records in another taxonomy. Use an [automated picklist](/reference/picklists/automated) so the list stays in sync. If you need cascading choices, you still use static picklists, just linked into a parent and child pair. See [Hierarchical](/reference/picklists/hierarchical).
</Warning>

## How it works

A static picklist is a named list. Each option has:

* A **code**: the value saved on the record. Codes are unique within the picklist (and unique among children of the same parent in a hierarchy).
* An optional **label** (the option's `description`): the text shown in the dropdown. When absent, the code is shown as its own label.
* A **position**: the order the options appear in. You set it by dragging rows in the editor.

When a dropdown uses the picklist, the submitter sees the labels and the record stores the chosen code. If you turn on "Allow new values", a submitter can also type a value that is not in the list yet, and that value becomes a real option when the submission is approved.

### Building and editing options

You edit options in a spreadsheet-style grid with a `code` column and a label column. You can:

* Add rows one at a time, or paste a block of rows straight from a spreadsheet.
* Reorder options by dragging.
* Convert a flat list into a [hierarchical](/reference/picklists/hierarchical) one when you need cascading choices.

There are two ways to reach the editor. Open the full Picklists area of the governance model and add a new static list, or create one inline from a dropdown field's settings without leaving the field editor (this inline path builds a flat list). Editing a list applies everywhere that list is used.

<Note>
  You cannot add or change options one at a time through the API. Options are managed as a set inside the picklist itself, or proposed by submitters and created on approval. There is no per-option "add" endpoint.
</Note>

### Allow new values (`allow_additions`)

When "Allow new values" is on (`allow_additions: true`), a submitter filling in a form can type a value that is not in the list. It appears as an "Add new ..." choice and, once selected, is marked as a new value on that submission only. It is not visible to other submissions.

When the submission is approved, any new values are added to the picklist as real options. The check uses the published version of the governance model that the submission was filled against, not the live toggle. So turning the switch on after a submission was started does not retroactively let that submission add values, and turning it off does not strip values from a submission filled while it was on. See [Letting submitters add options](/recipes/user-addable-options).

## Settings reference

| Setting           | Required | Default  | Description                                                                                                                                                                                               |
| ----------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | Yes      | None     | Stable identifier, unique within the governance model.                                                                                                                                                    |
| `name`            | Yes      | None     | Human-readable name, unique per governance model.                                                                                                                                                         |
| `type`            | Yes      | `static` | Must be the literal string `static`.                                                                                                                                                                      |
| `options`         | Yes      | None     | Array of `{ code, description?, ancestor_path? }`. Must hold at least one option unless `allow_additions: true`.                                                                                          |
| `allow_additions` | No       | `false`  | When `true`, submitters can propose new values while filling in a submission.                                                                                                                             |
| `parent_id`       | No       | None     | When set, links this list to a parent static picklist and makes it the child side of a hierarchy. Every option must then carry an `ancestor_path`. See [Hierarchical](/reference/picklists/hierarchical). |

Option shape:

| Option field    | Required         | Description                                                                                                           |
| --------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| `code`          | Yes              | Non-empty string, up to 100 characters. The value saved on records.                                                   |
| `description`   | No               | The label shown in the dropdown. Safe to rename at any time.                                                          |
| `ancestor_path` | Only on children | Ordered array of parent option codes from root to immediate parent. Required on every option once `parent_id` is set. |

## Example

A flat `UTM Sources` picklist for the Campaign URL Builder:

```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 }
```

Referenced from the `utm_source` dropdown field:

```yaml theme={null}
name: utm_source
type: dropdown
required: true
settings:
  picklist_id: utm-sources
```

A submission with `utm_source=facebook` saves `facebook` on the record while the form shows the label `Facebook`. Because `allow_additions` is on, a submitter could also type `reddit`. It is held as a new value on that submission and becomes a real option on `UTM Sources` once the submission is approved.

## Gotchas

* **Codes cannot be changed safely.** Records hold the code, not an internal id. Renaming a code (say `facebook` to `fb`) leaves every record that used the old code without a matching option, so those values no longer show a label. Rename the label freely, treat codes as fixed.
* **Codes are unique per picklist, and per parent.** Two top-level options cannot share a code, and neither can two children of the same parent. But two children under different parents can share a code, for example `other` under both `email` and `social`.
* **An empty list is allowed only with "Allow new values" on.** Without `allow_additions: true`, a static picklist needs at least one option. With it on, you can ship an empty list and let submitters populate it.
* **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. Toggling the switch after the fact does not change in-flight submissions.
* **Removing an option in the editor deletes it.** When you remove an option through the editor and save, it is gone from the list. A value that was already selected on past records but is no longer an option counts as invalid for new submissions. Re-adding an option with the same code makes it valid again.
* **Renaming the picklist itself is safe.** `name` is only a display label. The `id` is the stable reference that dropdowns and child picklists rely on.

## Related

* [Picklists overview](/reference/picklists)
* [Hierarchical picklist](/reference/picklists/hierarchical): a static picklist linked to a parent.
* [Automated picklist](/reference/picklists/automated): options sourced from another taxonomy's records.
* [Dropdown field](/reference/fields/dropdown): the field type that references picklists.
* [Letting submitters add options](/recipes/user-addable-options): a hands-on "Allow new values" walkthrough.
* [Tutorial Part 4: Static picklists](/tutorial/04-static-picklists)