> ## 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 4: Hierarchical picklists

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

In this part you build the `Countries` picklist (`us`, `ca`, `uk`) with a `Regions` level under it, then the `Country` and `Region` dropdown fields. When someone picks a country, the region dropdown shows only that country's regions. It takes seven short steps.

You need the `Marketing` governance model from [Part 3: Static picklists](/tutorial/03-static-picklists).

## How it works

You build a hierarchical picklist in one editor, as a chain of static picklists, one per level. Countries are the first level and regions are the second. Each region sits on the same row as the country it belongs to. When you save, each level becomes its own picklist, named after its column header and linked to the level above.

Two dropdown fields turn that into a cascade. `Country` points at `Countries` and `Region` points at `Regions`. You never tell `Region` which field to depend on: the field editor finds the dropdown that uses the parent picklist and links them for you. That is why `Country` comes first.

Until a country is picked, the region dropdown shows `Select "Country" first` instead of options. For the full rules, see the [hierarchical picklists reference](/reference/picklists/hierarchical).

## Steps

<Steps>
  <Step title="Create the Countries picklist">
    With the `Marketing` governance model open, click **Picklists** in the sidebar. Click **Create new**, then choose **Static Picklist**.

    Click the `Name` column header, type `Countries`, and press Enter. This header names the first level's picklist.
  </Step>

  <Step title="Add the country options">
    Add three rows. Type the code in **Code** and the display text in **Label**, the same as `Goals` in Part 3.

    | Code | Label |
    | - | - |
    | `us` | United States |
    | `ca` | Canada |
    | `uk` | United Kingdom |

    These are your parent options.
  </Step>

  <Step title="Add a second level for regions">
    Click **+ Level**, the last column header. Its tooltip reads **Add level**. A new column pair appears with the header `Level 2`.

    Click the header, type `Regions`, and press Enter. Each row now holds one path: a country on the left and one of its regions on the right.
  </Step>

  <Step title="Add the region options under their countries">
    When you finish, the grid in **Flat** view looks like this, one row per region:

    | Countries: Code | Countries: Label | Regions: Code | Regions: Label |
    | - | - | - | - |
    | `us` | United States | `ca` | California |
    | `us` | United States | `ny` | New York |
    | `us` | United States | `tx` | Texas |
    | `us` | United States | `fl` | Florida |
    | `ca` | Canada | `on` | Ontario |
    | `ca` | Canada | `qc` | Quebec |
    | `ca` | Canada | `bc` | British Columbia |
    | `uk` | United Kingdom | `eng` | England |
    | `uk` | United Kingdom | `sct` | Scotland |
    | `uk` | United Kingdom | `wls` | Wales |
    | `uk` | United Kingdom | `nir` | Northern Ireland |

    Start with the first region on each country's existing row. Type `ca` / `California` next to `us`, `on` / `Ontario` next to `ca`, and `eng` / `England` next to `uk`.

    Then add the rest by duplicating. Right-click the country's last row (the one with the region you just entered), choose **Duplicate row**, and change the copy's region code and label. The copy lands right below, so a country's rows stay together, in the order you add them. Do `us` first (`ny`, `tx`, `fl`), then `ca` (`qc`, `bc`), then `uk` (`sct`, `wls`, `nir`).

    <Warning>
      Check the country code on every row. The parent sits on the same row as its region, so a typo like `usa` instead of `us` raises no error. It creates a fourth country, `usa`, with that region under it. The editor does flag a region row with no country ("All parent levels must be filled") and a country whose rows are split up by other countries.
    </Warning>

    Switch the toolbar from **Flat** to **Grouped**. Each region now appears nested under its country, which is the quickest way to spot a stray row before you save.

    <Tip>
      A child code only has to be unique within its parent. `ca` is both Canada's country code and California's region code, which is fine because they sit on different levels.
    </Tip>
  </Step>

  <Step title="Save the picklist">
    Click **Save**. The editor saves two linked picklists, `Countries` and `Regions`, and both appear in the **Picklists** list.

    Once campaigns are running, avoid reworking the levels of this picklist. Every region is tied to its country, so moving regions to other countries means remapping existing records.
  </Step>

  <Step title="Create the Country Dropdown field">
    Click **Fields** in the sidebar, then **Create new**, and pick **Dropdown**. Set **Name** to `Country`. In **Picklist**, select `Countries`. Click **Save to draft**. The `Country` field appears in the field list.

    Leave **Enable multi-select mode** off. A cascade needs exactly one country at a time to decide which regions are valid.
  </Step>

  <Step title="Create the Region Dropdown field">
    Click **Create new** again and pick **Dropdown**. Set **Name** to `Region`. In **Picklist**, select `Regions`. Leave **Enable multi-select mode** off here too. Click **Save to draft**.

    The editor links `Region` to `Country` automatically. Once it does, the multi-select toggle on `Country` locks with "Not available when there are other fields that depend on this field."

    If you create `Region` before `Country`, the editor shows "The picklist requires a parent dropdown to be created first." Create `Country` first, then come back.
  </Step>
</Steps>

## Check your work

* Two linked picklists exist: `Countries` with `us`, `ca`, and `uk`, and `Regions` with four regions under `us`, three under `ca`, and four under `uk`.
* Two new fields exist: `Country` (Dropdown on `Countries`) and `Region` (Dropdown on `Regions`, cascading from `Country`).
* The governance model has six fields in total: `Campaign Name`, `Launch Date`, `Destination URL`, `Goal`, `Country`, and `Region`.

## Next up

You have your first cascade. In Part 8, picking `United States` filters the region dropdown to the four regions under `us`. The stored values are the codes (`us`, `ca`), which is what Part 6's `UTM Campaign` field splices together.

In [Part 5: The UTM cascade](/tutorial/05-utm-cascade), you build the same kind of hierarchy for UTM mediums and sources. For the standalone version of this cascade, see the [cascading dropdowns recipe](/recipes/cascading-dropdowns).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.