Cascading Dropdowns

Overview

Cascading dropdowns let you build dependent select chains — for example, selecting a Country first, which then filters the available States/Provinces, which then filters available Cities. Each subsequent dropdown's options are determined by the value selected in the parent dropdown.

Static Cascading

For smaller, static datasets, define the dependent options directly in the field configuration using a dependentOptions map:

// Parent field
{
  "type": "select",
  "name": "country",
  "label": "Country",
  "options": [
    { "label": "Nepal",  "value": "NP" },
    { "label": "India",  "value": "IN" }
  ]
}

// Child field
{
  "type": "select",
  "name": "province",
  "label": "Province / State",
  "dependsOn": "country",
  "dependentOptions": {
    "NP": [
      { "label": "Bagmati",   "value": "bagmati"   },
      { "label": "Gandaki",   "value": "gandaki"   },
      { "label": "Lumbini",   "value": "lumbini"   }
    ],
    "IN": [
      { "label": "Delhi",     "value": "delhi"     },
      { "label": "Maharashtra","value": "maharashtra"}
    ]
  }
}

API-driven Cascading

For larger datasets, use the Dynamic Options API with the dependsOn property. When the parent field value changes, the child field automatically re-fetches its options from the API with the parent value appended as a query parameter:

{
  "type": "select",
  "name": "district",
  "label": "District",
  "dependsOn": "province",
  "dynamicOptions": {
    "url": "https://api.example.com/districts",
    "method": "GET",
    "paramName": "province_id",
    "labelKey": "name",
    "valueKey": "id"
  }
}
// Fetches: /districts?province_id=bagmati