Skip to main content
A hierarchical picklist is a static picklist that is linked to a parent picklist. Each child option belongs to a specific parent option, so the child dropdown only offers the values that fit the parent the submitter already picked. This is how you build cascading dropdowns from admin-curated lists (country then region, medium then source, category then subcategory).

​
When to use it

  • A controlled vocabulary has a natural parent then child shape, and picking the parent should narrow the child.
  • You want to manage the child options as their own list, separate from the parent.
  • The values are admin-owned and fixed, not pulled from another taxonomy’s records.
Do not use a hierarchical picklist when every option is a peer with no parent. Use a flat static picklist instead. When the cascading values already live as records in another taxonomy, build the cascade with an automated picklist that has more than one level, not a hierarchical static one.

​
How it works

You link two static picklists by setting parent_id on the child to the parent picklist’s id. The child is otherwise an ordinary static picklist, with one addition: every child option carries an ancestor_path. ancestor_path is an ordered list of the parent option codes, from the top of the chain down to the immediate parent. A region option under the country us has ancestor_path: ["us"]. In a three-level list (category, subcategory, product), a product option under electronics then audio has ancestor_path: ["electronics", "audio"]. The cascade shows up at submission time through the dropdown field. The child field declares depends_on pointing at the parent field. As the submitter fills the form, the child dropdown offers only the options whose ancestor_path exactly equals the codes selected in the parent chain, in order. While any parent in the chain is empty, the child dropdown stays disabled. For a list deeper than two levels, give each level its own picklist and chain the links: level 3’s parent_id points at level 2, whose parent_id points at level 1. Each level’s options carry the full ancestor_path from the root down.

​
Settings reference

A hierarchical picklist uses the same settings as any static picklist. These are the ones that make it hierarchical.
SettingRequiredDefaultDescription
typeYesstaticAlways static. Hierarchy is created by parent_id, not a separate type.
parent_idYes, to link the listNoneThe id of the parent static picklist. Omit it and the list is flat.
optionsYesNoneThe child options. When parent_id is set, every option must include an ancestor_path.
options[].ancestor_pathYes on every child optionNoneOrdered list of parent option codes, root to immediate parent. Each code must resolve to a real option along the parent chain.
allow_additionsNofalseWhen true, submitters can propose a new code under the parent they have selected. See user-addable options.

​
Worked example

The Countries and Regions lists from the hierarchical picklists tutorial, where Regions is linked to Countries: 
# Parent picklist
- id: countries
  name: Countries
  type: static
  options:
    - { code: us, description: United States }
    - { code: ca, description: Canada }
    - { code: uk, description: United Kingdom }

# Child picklist, linked to countries
- id: regions
  name: Regions
  type: static
  parent_id: countries
  options:
    - { code: california, description: California,       ancestor_path: [us] }
    - { code: new_york,   description: New York,         ancestor_path: [us] }
    - { code: ontario,    description: Ontario,          ancestor_path: [ca] }
    - { code: bc,         description: British Columbia, ancestor_path: [ca] }
    - { code: england,    description: England,          ancestor_path: [uk] }
    - { code: scotland,   description: Scotland,         ancestor_path: [uk] }
The two dropdown 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
When the submitter picks country = us, the region dropdown offers only california and new_york, the two options whose ancestor_path is ["us"]. The same shape wires UTM medium then UTM source in the tutorial, with allow_additions: true on the child so marketers can add a new source under the medium they chose.

​
Gotchas

  • Codes are unique per parent, not globally. Two children of the same parent cannot share a code, but two children under different parents can. other can exist under both email and social. This is the most common point of confusion when building a hierarchical list.
  • Parent codes are effectively permanent. Children store the parent’s code in their ancestor_path, not its ID. Renaming us to usa on the parent leaves every child whose path starts with us without a matching parent, so those options stop appearing. Rename the parent’s description freely, but treat its codes as fixed once children reference them.
  • Every child option needs a complete ancestor_path. Omitting it on a linked list is rejected. The path must be the full chain from the root to the immediate parent, not just the immediate parent’s code.
  • An option pointing at a parent code that does not exist never shows. It simply never matches the parent selection, with no error to the submitter. Validate the list when you publish so dangling paths surface early.
  • Multi-select is not available. A dropdown cannot turn on multiple when its picklist is linked (has a parent_id or has children) or when the field uses depends_on. Cascading depends on a single parent value. Use separate fields if you need to capture several values at one level.
  • For record-sourced cascading, use an automated picklist instead. parent_id links two static lists. If your cascade should be driven by another taxonomy’s records, build an automated picklist with more than one level. It produces the same parent then child narrowing without hand-maintaining options.