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

# Part 5: Hierarchical picklists

> Build a two-level Countries and Regions picklist and two dropdown fields, where picking a country narrows the region list automatically.

<Info>
  **What you'll learn:** how a hierarchical (parent to child) picklist works, how its levels filter each other, and why the cascade wires itself once the picklists are linked.

  **What you'll build:** one two-level `Countries / Regions` hierarchical picklist and two dropdown fields (`country`, `region`) where picking a country narrows the region list.

  **Prerequisites:** [Part 4: Static picklists](/tutorial/04-static-picklists).
</Info>

## Why this matters

"Region" depends on "country": California is a US thing, Ontario is a Canadian thing, and nobody should ever see a form that lets them pick Ontario for the US. With two flat dropdowns and a hope that users read carefully, you end up with `country=us, region=ontario` in production and nothing catches it. A hierarchical picklist pushes that rule into the data model. Once a region option records which country it belongs to, the region dropdown filters itself the moment a country is picked, and the cascade is enforced for everyone.

## Concepts first

### Hierarchical picklist

A **hierarchical picklist** is a single Static picklist with more than one **level**. The first level holds the parent options (countries); the second level holds child options (regions). Each child option records its **ancestor path**: the parent code (or codes) it sits under. You build all the levels in one editor, not as separate picklists you link together. You can chain more than two levels, but the Campaign URL Builder sticks to two (Countries to Regions, and the UTM hierarchy in Part 6).

### Cascading dropdowns

Two dropdown fields turn a hierarchical picklist into a cascade: one field points at the parent level, the other at the child level. When a child dropdown is filled, it only offers options whose ancestor path matches the parent the user already chose. Pick `us` and the region dropdown shows California and New York. Pick `ca` and it shows Ontario and British Columbia. Change the country and the region clears, because a region from the old country no longer satisfies the cascade.

### The cascade wires itself

You do not manually tell the region field which field it depends on. When you point a dropdown at a child level of a hierarchical picklist, the field editor wires the parent relationship for you from the picklist's own structure. Your job is to build the two levels and create the two dropdowns. The link between them is automatic.

### Why multi-select is not available here

A flat Dropdown field can be single or multi-select. A cascading dropdown cannot be multi-select, because the cascade needs exactly one parent value at a time to decide which child options are valid. The editor hides the multi-select toggle on a cascading dropdown.

## Step-by-step

<Steps>
  <Step title="Create the Countries picklist">
    Open the `Marketing` GM, click **Picklists**, then **Create new** and choose **Static Picklist**. Name it `Countries`. The editor opens with a single level for your options.
  </Step>

  <Step title="Add the country options">
    In the first level, add three options: `us` / `United States`, `ca` / `Canada`, `uk` / `United Kingdom`. Enter the code on the left and the description on the right, the same as `Goals` in Part 4. These are your parent options.
  </Step>

  <Step title="Add a second level for regions">
    Click **Add level** (the trailing **Level** column header) to add a child level. Each row now has a parent option on the left and a child option on the right, so every region you add sits under one country.
  </Step>

  <Step title="Add the region options under their countries">
    Under `us`, add `california` / `California` (and, if you like, `new_york` / `New York`). Under `ca`, add `ontario` / `Ontario`. Under `uk`, add `england` / `England`. Each region's ancestor path is the country code it sits under. The tutorial needs only one region per country, but add more from the canonical example if you want.

    <Tip>
      A child code only has to be unique within its parent. You could legitimately have a `north` region under both `us` and `uk`, because they sit under different parents.
    </Tip>
  </Step>

  <Step title="Save the picklist">
    Click **Save**. `Countries` is now a single hierarchical picklist with two levels: countries at the top, regions nested underneath.
  </Step>

  <Step title="Create the country Dropdown field">
    Go to **Fields** on the GM and click **Create new field**. Name: `country`. Type: **Dropdown**. **Picklist**: pick the top (country) level of `Countries`. Save. The `country` field appears in the Fields list.
  </Step>

  <Step title="Create the region Dropdown field">
    Click **Create new field** again. Name: `region`. Type: **Dropdown**. **Picklist**: pick the region (child) level of `Countries`. Save. The editor wires the cascade to `country` automatically, and the multi-select toggle is hidden because this is a cascading dropdown.
  </Step>
</Steps>

<Note>📸 Screenshot coming soon: part 05 hierarchy editor</Note>

## Check your work

* A single `Countries` picklist exists with two levels: three countries (`us`, `ca`, `uk`) and at least one region nested under each.
* Two new fields exist: `country` (Dropdown on the country level) and `region` (Dropdown on the region level, cascading from `country`).
* The GM has six fields total now: `campaign_name`, `launch_date`, `destination_url`, `goal`, `country`, `region`.

## What you just built

The first cascade. When a user opens a campaign form in Part 8, picking `United States` in the country dropdown filters the region dropdown to California and New York; picking Canada filters it to Ontario and British Columbia. The stored values stay as codes (`us`, `california`), exactly what Part 7's `utm_campaign` field will splice together.

```mermaid theme={null}
flowchart LR
  subgraph PL[Countries picklist]
    L1[Level 1: countries<br/>us, ca, uk]
    L2[Level 2: regions<br/>california → us<br/>ontario → ca<br/>england → uk]
    L1 -.ancestor path.-> L2
  end
  CF[country field<br/>Dropdown → country level] -->|cascade| RF[region field<br/>Dropdown → region level]
```

## Gotchas

* **Every child option must sit under a valid parent.** If a region's parent code does not exist (a typo like `usa` instead of `us`), the editor flags the gap. Fix it by correcting the row's parent; no data is lost.
* **Multi-select is not available on a cascading dropdown.** The editor hides the toggle. See the [hierarchical picklists reference](/reference/picklists/hierarchical) for the full rule set.
* **The cascade comes from the picklist's structure, not a manual setting.** Because `region` points at a child level, the dependency on `country` is wired for you. If you ever swap `region` to a flat picklist, the cascade goes away.
* **Reworking the level structure of a live picklist is disruptive.** Every child option's ancestor path is tied to its parent, so re-parenting options after records exist means remapping them. Treat the hierarchy as settled once campaigns are running.

## Next up

[Part 6: User-addable picklists](/tutorial/06-user-addable-picklists). Build the UTM hierarchy, turn on `allow_additions` so submitters can propose new sources, and meet `filter_options` (which Part 8 configures for real). For the standalone version of this cascade, see the [cascading dropdowns recipe](/recipes/cascading-dropdowns).