台灣地址選擇器
縣市/鄉鎮市區二級聯動選單，自動帶出郵遞區號。
台灣縣市與鄉鎮市區的二級聯動下拉選單，內建可搜尋過濾的自寫下拉、選定行政區後自動帶出 3 碼郵遞區號徽章，並組合出完整地址預覽列（含一鍵複製），適合結帳、收件與會員資料表單。
載入預覽⋯
Playground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
<TaiwanAddressPicker />
安裝
npx shadcn@latest add https://webberui.com/r/taiwan-address-picker.json或在 components.json 設定 registries 後，改用 @webberui/taiwan-address-picker 安裝。
安裝依賴後，從 registry JSON（/r/taiwan-address-picker.json 的 files[0].content）複製 taiwan-address-picker.tsx 原始碼到你的 components/ui/ 目錄：
npm install motion lucide-react clsx tailwind-merge使用
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} />;
}也可以不傳 value 讓元件自行管理狀態，只透過 onChange 取得結果；另外匯出 formatTaiwanAddress(value) 可將地址物件組成「郵遞區號 縣市鄉鎮市區詳細地址」字串，TAIWAN_DISTRICTS 對照表也可直接取用。
Props
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
value | TaiwanAddress | — | 受控值，形狀為 { city, district, zip, detail }；不提供時元件內部自行管理 |
onChange | (value: TaiwanAddress) => void | — | 任一欄位變動時回傳完整地址物件（換縣市會清空鄉鎮市區與郵遞區號） |
showDetail | boolean | true | 是否顯示詳細地址輸入框 |
className | string | — | 透傳到外層容器 |
資料範圍
- 內建全部 22 縣市清單；六都與基隆市、新竹市、嘉義市、連江縣收錄完整行政區。
- 其餘縣市僅收錄 3–5 個代表行政區作為示範，下拉面板底部會顯示「示範資料」註記。
- 生產環境請依中華郵政「3+3 郵遞區號」官方資料擴充元件內的
TAIWAN_DISTRICTS對照表即可，結構不需更動。
可及性
- 下拉觸發鈕標註
aria-haspopup與aria-expanded，清單使用role="listbox"與role="option"（含aria-selected） - 面板開啟後自動聚焦搜尋框，支援上下方向鍵移動、Enter 選取、Escape 關閉，鍵盤導覽時選項自動捲動至可視範圍
- 使用者系統開啟「減少動態效果」時，面板展開、郵遞區號徽章彈出與預覽列展開皆改為即時顯示，不播放動畫