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

​
Two ways to cascade

Pick the path that matches where your child values live.

Hand-authored cascade

You own a fixed parent then child vocabulary. Build it from linked static picklists: a parent list and a child list that points at it with parent_id.

Record-sourced cascade

The values already exist as approved records in another taxonomy. Build it from one automated picklist with two or more settings.levels.
Both wire up the same way on the field side: the child dropdown field 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.
1

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

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

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

Create the parent dropdown field

In Fields, add a Dropdown field named country with its picklist set to Countries.
5

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

Attach both fields and publish

Add country and region to the taxonomy that uses them, then publish the governance model.

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

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

Create an automated picklist

In Picklists, add an Automated picklist and set its Source taxonomy to Clients.
3

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

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

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

Attach both fields and publish

Add client_region and client to the taxonomy that uses them, then publish the governance model.
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: 
# 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: 
- 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: 
- { 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.