Skip to main content
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.

​
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

1

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

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

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

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

Save the picklist

Click Save. Countries is now a single hierarchical picklist with two levels: countries at the top, regions nested underneath.
6

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

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.
📸 Screenshot coming soon: part 05 hierarchy editor

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

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