Address autocomplete

ThaiAddressAutocomplete is for forms where people can search an address by sub-district, district, province, or postal code.

Install

npx react-thaizip add autocomplete

The command adds the component plus utils and the address-index loading hook to the directories recorded in thaizip.config.json.

Basic usage

Import from the location generated in your project:

import { ThaiAddressAutocomplete } from '@/components/thai-address-autocomplete'

export function AddressField() {
  return <ThaiAddressAutocomplete onValueChange={(address) => console.log(address)} />
}

onValueChange receives ResolvedThaiAddress | null. Selecting a suggestion yields a structured address; typing an empty query clears an existing resolved selection with null.

Thai search

ค้นหาที่อยู่

ค้นหาที่อยู่ไทยด้วยการพิมพ์ข้อมูลส่วนใดส่วนหนึ่งของที่อยู่

English search

Use locale="en" for English labels, placeholders, and suggestions. The returned data still includes Thai and English names.

<ThaiAddressAutocomplete locale="en" onValueChange={(address) => console.log(address)} />

Address autocomplete

Search for a Thai address by typing any part of it.

Controlled value

Pass value to control the selection, or defaultValue to seed uncontrolled state. This example includes a clear button for the controlled value and shows the callback output.

const [address, setAddress] = useState<ResolvedThaiAddress | null>(null)

<ThaiAddressAutocomplete value={address} onValueChange={setAddress} />

ค้นหาที่อยู่

ค้นหาที่อยู่ไทยด้วยการพิมพ์ข้อมูลส่วนใดส่วนหนึ่งของที่อยู่

ที่อยู่ที่เลือก

null

Disabled and invalid states

Pass disabled to turn off the search field, or aria-invalid after failed form validation.

ค้นหาที่อยู่

ค้นหาที่อยู่ไทยด้วยการพิมพ์ข้อมูลส่วนใดส่วนหนึ่งของที่อยู่

ค้นหาที่อยู่

ค้นหาที่อยู่ไทยด้วยการพิมพ์ข้อมูลส่วนใดส่วนหนึ่งของที่อยู่

Props

Value

Prop	Type	Description
`value`	`ResolvedThaiAddress \| null`	Controlled value; pass `null` to clear it.
`defaultValue`	`ResolvedThaiAddress \| null`	Uncontrolled seed value; also pre-fills the initial search text.
`onValueChange`	`(address: ResolvedThaiAddress \| null) => void`	Called when an address is selected or cleared.

Search

Prop	Type	Description
`limit`	`number`	Maximum suggestions; passed to the core hook.
`debounce`	`number`	Search delay in milliseconds; passed to the core hook.
`threshold`	`number`	Minimum query length; passed to the core hook.

Field

Prop	Type	Description
`name`	`string`	Renders four hidden inputs for subdistrict, district, province, and zipcode.
`locale`	`'th' \| 'en'`	Text and label locale; defaults to `'th'`.
`disabled`	`boolean`	Disables the search input.
`required`	`boolean`	Marks the input as required.
`aria-invalid`	`React.AriaAttributes['aria-invalid']`	Marks the input as invalid.
`onBlur`	`React.FocusEventHandler<HTMLInputElement>`	Runs when the input loses focus.
`onError`	`(error: Error) => void`	Runs if the address index cannot load.

Text

Prop	Type	Description
`texts`	`Partial<ThaiAddressAutocompleteTexts>`	Overrides the placeholder, loading/error/empty states, and clear/retry labels.

Class slots

Prop	Applied to
`className`	Root wrapper
`inputClassName`	Search input
`popupClassName`	Results popup
`itemClassName`	Each result item

Ref

Prop	Type	Description
`ref`	`React.Ref<HTMLInputElement>`	Forwarded to the input.

See Forms to submit address values and Customization to change the presentation. For ordered address selection, see cascade select.

Address autocomplete

On this page