Cascading selects
What it combines
optionsSource— a serialisable options loader:url, pluspath,labelKey,valueKeywhen the response is not already[{ label, value }](Types){{field}}placeholders in theurl— each one makes the field depend on another- Select fields — the control stays disabled until its parent has a value
Pick a country, then a region, then a city. Change the country and the other two reset. The options come from static JSON files served with this page; nothing leaves it.
Pick a country, then a region, then a city…
import { FormBuilder } from '@saastro/forms';
/**
* Country → region → city. Each select asks its own endpoint, and the `{{field}}` in the URL
* is what makes it depend on the one above: no value yet → no request and the control stays
* disabled; the value changes → options are dropped, requested again and this field is cleared.
*/
export function createConfig({ base = '' }: { base?: string } = {}) {
return FormBuilder.create('cascading-selects')
.layout('manual')
.columns(12)
.addField('country', (f) =>
f
.type('select')
.label('Country')
.required()
.options([
{ value: 'es', label: 'Spain' },
{ value: 'fr', label: 'France' },
])
.columns({ default: 12, md: 4 }),
)
.addField('region', (f) =>
f
.type('select')
.label('Region')
.required()
.optionsSource({ url: `${base}/demo/regions/{{country}}.json` })
.columns({ default: 12, md: 4 }),
)
.addField('city', (f) =>
f
.type('select')
.label('City')
.required()
.optionsSource({ url: `${base}/demo/cities/{{region}}.json` })
.columns({ default: 12, md: 4 }),
)
.addStep('place', ['country', 'region', 'city'])
.initialStep('place')
.build();
}The code
The Code tab above is the whole form. Each dependent select declares only its endpoint:
.addField('region', (f) =>
f.type('select').label('Region').required()
.optionsSource({ url: '/api/regions/{{country}}' }),
)
How it works
- Dependencies come from the URL — every
{{field}}inurlcounts, anddependsOn: ['other']adds fields the server reads from somewhere else. - Nothing is requested while a parent is empty, and the control is disabled.
- When a parent changes, the old options are dropped and the new ones requested. If the parent is emptied the field’s value is cleared, and when the new options arrive a value that is no longer among them is removed. Because the region is cleared, the city loses its parent too, so the change cascades down.
- Values are URL-encoded (
encodeURIComponent) before they replace the placeholder.
Caveats
- A placeholder cannot sit in the host — only after the origin (
https://api.example.com/regions/{{country}}is fine,https://{{country}}.example.comis not). - Dependencies must be single values (text or number). A multiple field as a parent has no value to substitute and leaves the options empty.
loadOptionswins overoptionsSourcewhen both are set, and it is a function: it does not survive the Hub or the builder’s JSON.- The endpoint runs in the browser, so it cannot hold secrets, and it must allow your origin (CORS).
- Do not trust the browser’s choice — the options are fetched on the client, so on the server check the country, region and city against your own data.
Variations
- Point
pathatdata.itemsand setlabelKey/valueKeyfor an existing API. - Use
comboboxwithserverSearchandsearchParamfor long lists. - Add
dependsOnfor a parent that is not in the URL (a header, a cookie the endpoint reads).