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

# Hierarchical picklist

> A static picklist linked to a parent picklist so a child dropdown only offers the options that match the parent selection.

<Info>
  A hierarchical picklist is a [static picklist](/reference/picklists/static) that is linked to a parent picklist. Each child option belongs to a specific parent option, so the child dropdown only offers the values that fit the parent the submitter already picked. This is how you build cascading dropdowns from admin-curated lists (country then region, medium then source, category then subcategory).
</Info>

## When to use it

* A controlled vocabulary has a natural parent then child shape, and picking the parent should narrow the child.
* You want to manage the child options as their own list, separate from the parent.
* The values are admin-owned and fixed, not pulled from another taxonomy's records.

<Warning>
  Do not use a hierarchical picklist when every option is a peer with no parent. Use a flat [static picklist](/reference/picklists/static) instead. When the cascading values already live as records in another taxonomy, build the cascade with an [automated picklist](/reference/picklists/automated) that has more than one level, not a hierarchical static one.
</Warning>

## How it works

You link two static picklists by setting `parent_id` on the child to the parent picklist's `id`. The child is otherwise an ordinary static picklist, with one addition: every child option carries an `ancestor_path`.

`ancestor_path` is an ordered list of the parent option codes, from the top of the chain down to the immediate parent. A region option under the country `us` has `ancestor_path: ["us"]`. In a three-level list (category, subcategory, product), a product option under `electronics` then `audio` has `ancestor_path: ["electronics", "audio"]`.

The cascade shows up at submission time through the [dropdown field](/reference/fields/dropdown). The child field declares `depends_on` pointing at the parent field. As the submitter fills the form, the child dropdown offers only the options whose `ancestor_path` exactly equals the codes selected in the parent chain, in order. While any parent in the chain is empty, the child dropdown stays disabled.

For a list deeper than two levels, give each level its own picklist and chain the links: level 3's `parent_id` points at level 2, whose `parent_id` points at level 1. Each level's options carry the full `ancestor_path` from the root down.

## Settings reference

A hierarchical picklist uses the same settings as any [static picklist](/reference/picklists/static). These are the ones that make it hierarchical.

| Setting                   | Required                  | Default  | Description                                                                                                                                  |
| ------------------------- | ------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                    | Yes                       | `static` | Always `static`. Hierarchy is created by `parent_id`, not a separate type.                                                                   |
| `parent_id`               | Yes, to link the list     | None     | The `id` of the parent static picklist. Omit it and the list is flat.                                                                        |
| `options`                 | Yes                       | None     | The child options. When `parent_id` is set, every option must include an `ancestor_path`.                                                    |
| `options[].ancestor_path` | Yes on every child option | None     | Ordered list of parent option codes, root to immediate parent. Each code must resolve to a real option along the parent chain.               |
| `allow_additions`         | No                        | `false`  | When true, submitters can propose a new code under the parent they have selected. See [user-addable options](/recipes/user-addable-options). |

## Worked example

The `Countries` and `Regions` lists from the [hierarchical picklists tutorial](/tutorial/05-hierarchical-picklists), where `Regions` is linked to `Countries`:

```yaml theme={null}
# Parent picklist
- id: countries
  name: Countries
  type: static
  options:
    - { code: us, description: United States }
    - { code: ca, description: Canada }
    - { code: uk, description: United Kingdom }

# Child picklist, linked to countries
- id: regions
  name: Regions
  type: static
  parent_id: countries
  options:
    - { code: california, description: California,       ancestor_path: [us] }
    - { code: new_york,   description: New York,         ancestor_path: [us] }
    - { code: ontario,    description: Ontario,          ancestor_path: [ca] }
    - { code: bc,         description: British Columbia, ancestor_path: [ca] }
    - { code: england,    description: England,          ancestor_path: [uk] }
    - { code: scotland,   description: Scotland,         ancestor_path: [uk] }
```

The two dropdown fields wire the cascade with `depends_on`:

```yaml theme={null}
- name: country
  type: dropdown
  settings: { picklist_id: countries }

- name: region
  type: dropdown
  settings:
    picklist_id: regions
    depends_on: country
```

When the submitter picks `country = us`, the `region` dropdown offers only `california` and `new_york`, the two options whose `ancestor_path` is `["us"]`. The same shape wires UTM medium then UTM source in the tutorial, with `allow_additions: true` on the child so marketers can add a new source under the medium they chose.

## Gotchas

* **Codes are unique per parent, not globally.** Two children of the same parent cannot share a code, but two children under different parents can. `other` can exist under both `email` and `social`. This is the most common point of confusion when building a hierarchical list.
* **Parent codes are effectively permanent.** Children store the parent's code in their `ancestor_path`, not its ID. Renaming `us` to `usa` on the parent leaves every child whose path starts with `us` without a matching parent, so those options stop appearing. Rename the parent's `description` freely, but treat its codes as fixed once children reference them.
* **Every child option needs a complete `ancestor_path`.** Omitting it on a linked list is rejected. The path must be the full chain from the root to the immediate parent, not just the immediate parent's code.
* **An option pointing at a parent code that does not exist never shows.** It simply never matches the parent selection, with no error to the submitter. Validate the list when you publish so dangling paths surface early.
* **Multi-select is not available.** A dropdown cannot turn on `multiple` when its picklist is linked (has a `parent_id` or has children) or when the field uses `depends_on`. Cascading depends on a single parent value. Use separate fields if you need to capture several values at one level.
* **For record-sourced cascading, use an automated picklist instead.** `parent_id` links two static lists. If your cascade should be driven by another taxonomy's records, build an [automated picklist](/reference/picklists/automated) with more than one `level`. It produces the same parent then child narrowing without hand-maintaining options.

## Related

* [Static picklist](/reference/picklists/static): the flat case. A hierarchical list is a static list with `parent_id`.
* [Automated picklist](/reference/picklists/automated): record-sourced lists, which support cascading through multiple levels.
* [Records](/reference/records): the approved data behind automated picklists.
* [Dropdown field](/reference/fields/dropdown): how `depends_on` sets up the cascade from the field side.
* [Cascading dropdowns recipe](/recipes/cascading-dropdowns): a hands-on walkthrough.
* [Tutorial Part 5: Hierarchical picklists](/tutorial/05-hierarchical-picklists)