Taiwan Address Picker

Two-level cascading selects for city/county and township/district, filling in the postal code automatically.

Two-level cascading dropdowns for Taiwan's cities/counties and townships/districts, with a hand-written searchable dropdown, a 3-digit postal code badge filled in automatically once a district is chosen, and a full address preview line (with one-click copy) assembled from the parts — suited to checkout, shipping, and member profile forms.

Loading preview…

npx shadcn@latest add https://webberui.com/r/taiwan-address-picker.json

Playground

Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.

Show the detailed address fieldsshowDetail

Component widthclassName

<TaiwanAddressPicker />

Installation

npx shadcn@latest add https://webberui.com/r/taiwan-address-picker.json

Or, once registries are configured in components.json, install it as @webberui/taiwan-address-picker.

Usage

import * as React from "react";
import {
  TaiwanAddressPicker,
  type TaiwanAddress,
} from "@/components/ui/taiwan-address-picker";

function CheckoutForm() {
  const [address, setAddress] = React.useState<TaiwanAddress>({
    city: "",
    district: "",
    zip: "",
    detail: "",
  });

  return <TaiwanAddressPicker value={address} onChange={setAddress} />;
}

You can also omit value and let the component manage the state itself, taking the result from onChange alone. formatTaiwanAddress(value) is also exported and assembles an address object into a "postal code, city/county, township/district, street address" string, and the TAIWAN_DISTRICTS lookup table can be used directly too.

Props

Prop	Type	Default	Description
`value`	`TaiwanAddress`	—	Controlled value, shaped `{ city, district, zip, detail }`; when omitted, the component manages it internally
`onChange`	`(value: TaiwanAddress) => void`	—	Returns the complete address object whenever any field changes (changing the city/county clears the district and postal code)
`showDetail`	`boolean`	`true`	Whether to show the street address input
`className`	`string`	—	Forwarded to the outer container

Data coverage

All 22 cities and counties are included; the six special municipalities plus Keelung City, Hsinchu City, Chiayi City, and Lienchiang County have their full set of districts.
The remaining cities and counties include only 3–5 representative districts as a demo, and the bottom of the dropdown panel notes that it is demo data.
For production, extend the component's TAIWAN_DISTRICTS lookup table from Chunghwa Post's official "3+3 postal code" data — the structure needs no changes.

Accessibility

The dropdown trigger carries aria-haspopup and aria-expanded, and the list uses role="listbox" and role="option" (with aria-selected)
Opening the panel focuses the search box automatically, with up/down arrow keys to move, Enter to select, and Escape to close; keyboard navigation scrolls the option into view automatically
When the user has "reduce motion" enabled at the system level, the panel expansion, the postal code badge pop, and the preview line expansion all show instantly with no animation