Taiwan Address Picker

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.

Playground

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

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

<TaiwanAddressPicker/>

    </div>
  );
}

Installation

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

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

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