The Cascading Dropdown Widget is a multi-level dropdown component where each selection dynamically filters and controls the options of the next dropdown in the sequence.
This widget enables hierarchical data selection, such as location (Province → District → Sector → …), categories, or other parent-child datasets. It fetches data from configured APIs and ensures that dependent fields update automatically based on the parent’s selected value. The widget supports exclusion of specific items, placeholder customization, and flexible dataset bindings, making it suitable for structured data entry in service applications.
Complete JSON Object
{
"key":"InputKey",
"label": "Cascading Dropdown"
"type":"customcascadingdropdowns",
"props":{
"required":true,
"label":"label",
"configs":[
{
"key":"province",
"label":"Province",
"bindlabel":"name",
"bindvalue":"",
"placeholder":"Select provinces",
"parent":null,
"required":true,
"dataset":{
"url":"http://localhost:8000/location/api/v1/provinces",
"dataField":"data.content"
}
"excludedItems": ["1"],
"excludedItemKey": "value"
},
{
"key":"district",
"label":"District",
"bindlabel":"name",
"bindvalue":"",
"placeholder":"Select district",
"parent":"province",
"required":true,
"parentBindKey":"id",
"dataset":{
"url":"http://localhost:8000/location/api/v1/districts",
"dataField":"data.content"
}
},
{
"key":"sector",
"label":"Sector",
"bindlabel":"name",
"bindvalue":"",
"placeholder":"Select sector",
"parent":"district",
"required":true,
"parentBindKey":"id",
"dataset":{
"url":"http://localhost:8000/location/api/v1/sectors",
"dataField":"data.content"
}
}
]
}
}
Important: The field expects a simple get url to fetch data as it will append the parent key for the dependant drop downs.
Allowed Custom Properties
Allowed Validations
validator-(n)
Missing to be configured via UI
Excluding Locations in Location widget
To exclude some data set items on the location widget, add an array of the excludedItemKey of the data set (in this example below, the value property; and also add excludedItems values you want to exclude (in the example below, (values 1, and 4 - NORTH and KIGALI).
{
"key": "LocalLocation85bnLj7MuR",
"id": "formly_19_customcascadingdropdowns_LocalLocation85bnLj7MuR_1",
"type": "customcascadingdropdowns",
"props": {
"label": "Location Widget",
"configs": [
{
"key": "PROVINCEwrIWY",
"label": "Location Widget Province",
"parent": null,
"dataset": {
"url": "/admin/v1/dataset-items/by-dataset-code/PROVINCE",
"dataField": "data",
"useBaseUrl": true
},
"required": false,
"bindlabel": "label",
"bindvalue": "",
"placeholder": "Select Location Widget Province",
"excludedItems": [
"4",
"1"
],
"excludedItemKey": "value"
},
{
"key": "DISTRICTwrIWY",
"label": "Location Widget District",
"parent": "PROVINCEwrIWY",
"dataset": {
"url": "/admin/v1/dataset-items/by-details",
"dataField": "data",
"useBaseUrl": true
},
"required": false,
"bindlabel": "label",
"bindvalue": "",
"placeholder": "Select Location Widget District",
"parentBindKey": "id"
},
{
"key": "SECTORwrIWY",
"label": "Location Widget Sector",
"parent": "DISTRICTwrIWY",
"dataset": {
"url": "/admin/v1/dataset-items/by-details",
"dataField": "data",
"useBaseUrl": true
},
"required": false,
"bindlabel": "label",
"bindvalue": "",
"placeholder": "Select Location Widget Sector",
"parentBindKey": "id"
},
{
"key": "CELLwrIWY",
"label": "Location Widget Cell",
"parent": "SECTORwrIWY",
"dataset": {
"url": "/admin/v1/dataset-items/by-details",
"dataField": "data",
"useBaseUrl": true
},
"required": false,
"bindlabel": "label",
"bindvalue": "",
"placeholder": "Select Location Widget Cell",
"parentBindKey": "id"
},
{
"key": "VILLAGEwrIWY",
"label": "Location Widget Village",
"parent": "CELLwrIWY",
"dataset": {
"url": "/admin/v1/dataset-items/by-details",
"dataField": "data",
"useBaseUrl": true
},
"required": false,
"bindlabel": "label",
"bindvalue": "",
"placeholder": "Select Location Widget Village",
"parentBindKey": "id"
}
],
"disabled": false,
"required": false,
"placeholder": "",
"dragDisabled": true,
"nonConfigurable": false
},
"defaultValue": null,
"expressions": {},
"validation": {
"messages": {}
},
"validators": null,
"asyncValidators": null
}
Backward Compatibility Notice
For older services using a location widget with country and city fields: (configured before : ui-common- version: 0.2.458 or 21/Jul/2025)
To ensure proper cleanup of the related country and city fields when the location widget settings are updated, you must manually link these fields to the widget using the locationWidgetKey property.
Steps to update:
country and city fields in your configuration."locationWidgetKey": "locationWidgetKeyValue”
"locationWidgetKeyValue" with the actual key of your location widget.This ensures proper synchronisation and cleanup behaviour.