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

# Cascading dropdowns

> Build a child dropdown that narrows to the parent selection, either from hand-authored lists or live from another taxonomy's records.

<Info>
  A cascade is a child dropdown whose options narrow based on what the submitter picked in a parent dropdown. Pick a country, and the region dropdown shows only that country's regions. There are two ways to build one, and this recipe covers both.
</Info>

## Two ways to cascade

Pick the path that matches where your child values live.

<CardGroup cols={2}>
  <Card title="Hand-authored cascade" icon="list-tree">
    You own a fixed parent then child vocabulary. Build it from linked [static picklists](/reference/picklists/static): a parent list and a child list that points at it with `parent_id`.
  </Card>

  <Card title="Record-sourced cascade" icon="refresh-cw">
    The values already exist as approved records in another taxonomy. Build it from one [automated picklist](/reference/picklists/automated) with two or more `settings.levels`.
  </Card>
</CardGroup>

Both wire up the same way on the field side: the child [dropdown field](/reference/fields/dropdown) sets `depends_on` to the parent field, and the child dropdown only offers options that match the parent selection. The difference is only the source of the options.

## Path A: hand-authored cascade (linked static picklists)

Use this when the parent and child values are a controlled vocabulary you maintain, like country then region.

<Steps>
  <Step title="Create the parent picklist">
    Open your governance model, go to **Picklists**, and add a new **Static** picklist named `Countries`. Leave **Parent picklist** empty. Add options: `us` with label `United States`, `ca` with label `Canada`, `uk` with label `United Kingdom`. Save.
  </Step>

  <Step title="Create the child picklist linked to the parent">
    Add another **Static** picklist named `Regions`. Set its **Parent picklist** to `Countries`. The list is now hierarchical, and every option must name its parent.
  </Step>

  <Step title="Add child options with a parent code">
    In `Regions`, each option has a parent selector that records its `ancestor_path` (the code of the option it sits under). Add `california` (parent `us`), `new_york` (parent `us`), `ontario` (parent `ca`), `bc` (parent `ca`), `england` (parent `uk`), `scotland` (parent `uk`).
  </Step>

  <Step title="Create the parent dropdown field">
    In **Fields**, add a **Dropdown** field named `country` with its picklist set to `Countries`.
  </Step>

  <Step title="Create the child dropdown field and depend it on the parent">
    Add a **Dropdown** field named `region` with its picklist set to `Regions`. Set **Depends on** to `country`. The multi-select toggle disappears, because a cascade needs exactly one parent value.
  </Step>

  <Step title="Attach both fields and publish">
    Add `country` and `region` to the taxonomy that uses them, then publish the governance model.
  </Step>
</Steps>

### What the submitter sees

Open a submission for that taxonomy. The `region` dropdown is disabled until `country` is set. Pick `United States`, and `region` offers only `California` and `New York`. Switch to `Canada`, and `region` clears and shows only `Ontario` and `British Columbia`.

## Path B: record-sourced cascade (automated picklist with levels)

Use this when the cascade values already live as approved records in another taxonomy, for example a `Clients` taxonomy where each client record carries a `region`. One automated picklist with two levels produces the cascade.

<Steps>
  <Step title="Make sure the source taxonomy has approved records">
    The cascade reads the approved records of the source taxonomy, so the `Clients` taxonomy needs some approved records, each with a `region` value and a `client_name`.
  </Step>

  <Step title="Create an automated picklist">
    In **Picklists**, add an **Automated** picklist and set its **Source taxonomy** to `Clients`.
  </Step>

  <Step title="Add the root level">
    Click **+ Level** and pick `region` as the first source field. This is `levels[0]`, the root of the cascade. Its options are the distinct `region` values across approved client records.
  </Step>

  <Step title="Add the child level">
    Click **+ Level** again and pick `client_name`. This becomes `levels[1]`, narrowed by the region chosen above. Optionally set this level's **label field** so the dropdown shows a friendly name.
  </Step>

  <Step title="Create the two dropdown fields">
    In **Fields**, add a **Dropdown** field named `client_region` pointing at this picklist. Add a second **Dropdown** field named `client`, point it at the same picklist, set **Depends on** to `client_region`, and set its level to `client_name`.
  </Step>

  <Step title="Attach both fields and publish">
    Add `client_region` and `client` to the taxonomy that uses them, then publish the governance model.
  </Step>
</Steps>

Each level is `{ source_field_id, label_field_id? }`. One level is a plain dropdown; two or more cascade. The cascade narrows by every selection above it: once a region is chosen, the `client` dropdown offers only the client names whose records match that region.

### What the submitter sees

The `client_region` dropdown lists every distinct region across approved client records. After they pick one, the `client` dropdown offers only the clients in that region. When a new client record is approved, it appears in these dropdowns automatically, with no governance-model change.

## Worked example

A campaign form asks for a country, then a region inside that country. With hand-authored lists, the two picklists look like this:

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

# Child picklist, linked to the parent
- id: regions
  name: Regions
  type: static
  parent_id: countries
  options:
    - { code: california, description: California,       ancestor_path: [us] }
    - { code: ontario,    description: Ontario,          ancestor_path: [ca] }
```

The same country then region cascade, but sourced from a `Clients` taxonomy's records, is one automated picklist with two levels:

```yaml theme={null}
- id: clients_picklist
  name: Clients
  type: automated
  source_taxonomy_id: clients_taxonomy
  settings:
    levels:
      - { source_field_id: region }                                 # levels[0], the root
      - { source_field_id: client_name, label_field_id: client_name } # levels[1], narrowed by region
```

In both cases the 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 }
```

## Gotchas

* **A typoed parent code silently shows nothing.** In a hand-authored cascade, if a child option's `ancestor_path` points at a code the parent does not have (`usa` instead of `us`), that option never matches a parent selection and never appears, with no error to the submitter. Check the child's parent codes when an option goes missing.
* **Parent codes are effectively permanent.** Children store the parent's code, not an internal id. Renaming `us` to `usa` on the parent leaves every child under it orphaned. Rename a label freely, but treat parent codes as fixed once children reference them.
* **Multi-select is unavailable on a cascading child.** A dropdown cannot turn on `multiple` when its picklist is linked (or has children) or when the field sets `depends_on`. A cascade needs exactly one parent value to decide which children are valid.
* **An automated cascade reads approved records only.** A record-sourced child shows nothing until the source taxonomy has approved records with a matching parent value. Drafts do not count, and deleted source records drop out.
* **The two approaches do not mix on one picklist.** A static list cascades through `parent_id` and linked child lists. An automated list cascades through `settings.levels`. There is no `parent_id` on an automated picklist and no levels on a static one.

## Related

* [Hierarchical picklist](/reference/picklists/hierarchical): the hand-authored cascade, in depth.
* [Automated picklist](/reference/picklists/automated): the record-sourced cascade, in depth.
* [Dropdown field](/reference/fields/dropdown): `depends_on` and how a cascade is wired from the field side.
* [Automated picklist recipe](/recipes/automated-picklist): a full record-sourced setup.
* [Tutorial Part 5: Hierarchical picklists](/tutorial/05-hierarchical-picklists)