Address cascade select
Choose province, district, and sub-district in order
ThaiAddressCascadeSelect is for forms where people choose an address in the order province → district → sub-district.
Install
npx react-thaizip add cascade-selectThe command adds the component, utils, the address-index loading hook, and the cascade-state hook to the directories recorded in thaizip.config.json.
Basic usage
Import from the location generated in your project:
import { ThaiAddressCascadeSelect } from '@/components/thai-address-cascade-select'
export function AddressField() {
return <ThaiAddressCascadeSelect onValueChange={(address) => console.log(address)} />
}onValueChange receives ResolvedThaiAddress | null once all three levels have been chosen.
Thai choices
เลือกจังหวัด อำเภอ/เขต และตำบล/แขวงตามลำดับ
English choices
Use locale="en" for English labels and options.
<ThaiAddressCascadeSelect locale="en" onValueChange={(address) => console.log(address)} />Choose a province, district, and sub-district in order.
Controlled value
Pass value to control the full selection, or defaultValue to seed the selected address. This example includes a clear button and shows the callback value.
const [address, setAddress] = useState<ResolvedThaiAddress | null>(null)
<ThaiAddressCascadeSelect value={address} onValueChange={setAddress} />เลือกจังหวัด อำเภอ/เขต และตำบล/แขวงตามลำดับ
null
Changing a parent choice
After a complete selection, changing the province or district emits onValueChange(null) and clears downstream selections that no longer match. The person then chooses the remaining address levels again.
Disabled and invalid states
Pass disabled to disable every select, or aria-invalid to mark all three triggers invalid.
เลือกจังหวัด อำเภอ/เขต และตำบล/แขวงตามลำดับ
เลือกจังหวัด อำเภอ/เขต และตำบล/แขวงตามลำดับ
Props
Value
| Prop | Type | Description |
|---|---|---|
value | ResolvedThaiAddress | null | Controlled value; pass null to clear it. |
defaultValue | ResolvedThaiAddress | null | Uncontrolled seed value; pre-selects the complete address chain. |
onValueChange | (address: ResolvedThaiAddress | null) => void | Called when an address is completed or cleared. |
Field
| Prop | Type | Description |
|---|---|---|
name | string | Renders four hidden inputs for subdistrict, district, province, and zipcode. |
locale | 'th' | 'en' | Label and option locale; defaults to 'th'. |
disabled | boolean | Disables all selects. |
required | boolean | Marks all three selects as required. |
aria-invalid | React.AriaAttributes['aria-invalid'] | Marks all three triggers invalid. |
onBlur | React.FocusEventHandler<HTMLButtonElement> | Runs when the province trigger loses focus. |
onError | (error: Error) => void | Runs if the address index cannot load. |
Text
| Prop | Type | Description |
|---|---|---|
texts | Partial<ThaiAddressCascadeSelectTexts> | Overrides labels, placeholders, and loading/error/retry text. |
Class slots
| Prop | Applied to |
|---|---|
className | Root grid wrapper |
labelClassName | Every field label |
triggerClassName | Select triggers and the postal-code input |
popupClassName | Option popups |
itemClassName | Each option item |
Ref
| Prop | Type | Description |
|---|---|---|
ref | React.Ref<HTMLButtonElement> | Forwarded to the province trigger, the cascade's primary control. |
Both ref and onBlur target the province trigger, not the district or sub-district trigger.
Related guides
See Forms to submit address values and Customization to change the presentation. For free-text search, see autocomplete.