@inverz/world-address
v1.0.2
Published
Address form for every country in React: fields, order, labels and postcode rules per country, level 1-3 place lists with postcode autofill for 100+ countries, one neutral address shape
Readme
@inverz/world-address
ฟอร์มที่อยู่ทุกประเทศสำหรับ React รู้ว่าแต่ละประเทศใช้ช่องอะไร เรียงลำดับแบบไหน เรียกแต่ละช่องว่าอะไร ช่องไหนบังคับกรอก และรหัสไปรษณีย์ต้องเป็นรูปแบบไหน ค่าที่ได้ใช้ชื่อช่องกลางชุดเดียวกันทุกประเทศ (level1 level2 level3 postalCode) ถ้าพิมพ์รหัสไปรษณีย์ของประเทศที่มีข้อมูล ช่องจังหวัดและเมืองจะเติมให้เอง ทำงานในเบราว์เซอร์ทั้งหมด ไม่ต้องมี server หรือ API key
Address form for every country in React. Uses Google's address metadata for 252 countries (fields, order, labels, required fields, postcode patterns), plus place lists for 240 countries and postcode autofill for 109. Every country produces the same address shape.
ติดตั้ง
npm i @inverz/world-addressใช้งาน
import "@inverz/world-address/style.css";
import { WorldAddressForm, emptyAddress } from "@inverz/world-address";
function Example() {
const [address, setAddress] = useState(emptyAddress("TH"));
return (
<WorldAddressForm
value={address}
onChange={(next, { valid, errors }) => setAddress(next)}
/>
);
}- เปลี่ยนประเทศแล้วช่องและป้ายชื่อเปลี่ยนตาม เช่น ไทย: ตำบล / อำเภอ / จังหวัด (กรุงเทพฯ: แขวง / เขต), สหรัฐฯ: City / State / ZIP, ญี่ปุ่น: 〒 → Prefecture → City, เยอรมนีไม่มีช่องรัฐ
- พิมพ์รหัสไปรษณีย์แล้วระบบเติมรัฐ/จังหวัดและเมืองให้ ถ้ารหัสนั้นใช้หลายพื้นที่ (เช่น 83000 ใช้ทั้งภูเก็ตและเกาะยาว) จะเลือกพื้นที่ที่ใช้รหัสนั้นมากที่สุด และมีปุ่มให้สลับ
- ช่องค้นหาด้านบนพิมพ์ครั้งเดียวได้ทั้งตำบล อำเภอ จังหวัด และรหัสไปรษณีย์ (
"hat yai","silom bangkok","10500") - ช่องเมืองและตำบลมีรายการให้เลือก แต่พิมพ์เองได้เสมอ เพราะข้อมูลของบางประเทศไม่ครบ
- ข้อมูลพื้นที่แยกไฟล์ต่อประเทศ และโหลดเฉพาะประเทศที่ผู้ใช้เลือก
ค่าที่ได้ (คำกลาง)
onChange(address, validation) ได้ object รูปแบบเดียวกันทุกประเทศ:
{
country: "TH", // ISO 3166-1 alpha-2
name: "", organization: "",
line1: "99/1 ถนนสีลม", // บ้านเลขที่ อาคาร ถนน
line2: "", line3: "",
level3: "สีลม", // ตำบล/แขวง · neighborhood · colonia · 동
level3Code: "100402", // รหัสทางการของพื้นที่ (ถ้ามี)
level2: "บางรัก", // อำเภอ/เขต · city · 市区町村
level2Code: "1004",
level1: "กรุงเทพมหานคร", // จังหวัด · state · prefecture
level1Code: "10", // ISO 3166-2 ไม่มีรหัสประเทศนำหน้า แบบ Stripe/Shopify ("CA", "13")
postalCode: "10500",
sortingCode: "" // CEDEX ของฝรั่งเศส และบางประเทศ
}เทียบกับมาตรฐาน
| ของเรา | HTML autocomplete | Google address data | Schema.org | Stripe | Shopify |
|---|---|---|---|---|---|
| country | country | country | addressCountry | country | countryCode |
| line1–line3 | address-line1–3 | address_lines | streetAddress | line1, line2 | address1, address2 |
| level1 / level1Code | address-level1 | administrative_area | addressRegion | state | province / provinceCode |
| level2 | address-level2 | locality | addressLocality | city | city |
| level3 | address-level3 | dependent_locality | — | — | — |
| postalCode | postal-code | postal_code | postalCode | postal_code | zip |
| sortingCode | — | sorting_code | — | — | — |
ความหมายของแต่ละระดับเป็นแบบเดียวกับ Google (ข้อมูลที่ Chrome และ Android ใช้กรอกที่อยู่) ชื่อพื้นที่ที่บันทึกอาจเป็นภาษาไทยหรืออังกฤษตามหน้าเว็บ ให้ใช้ช่อง …Code เทียบกัน
รหัสพื้นที่ (level2Code, level3Code) มีเฉพาะประเทศที่ข้อมูลมีรหัสทางการ: ไทย (กรมการปกครอง), เม็กซิโก (INEGI), เกาหลีใต้, จีน (GB/T 2260), โคลอมเบีย (DIVIPOLA), เปรู (UBIGEO), โปรตุเกส ประเทศอื่นเป็นค่าว่าง
Props
| prop | ค่าเริ่มต้น | |
|---|---|---|
| value / defaultValue | | ที่อยู่ (controlled / uncontrolled) |
| onChange | | (address, { valid, errors }) => void |
| locale | "th" | ภาษาของป้ายและชื่อประเทศ "th" หรือ "en" |
| defaultCountry | "TH" | ประเทศเมื่อ value ยังไม่มี |
| countries | ทุกประเทศ | จำกัดรายการประเทศ เช่น ["TH", "LA", "KH", "MM", "VN", "MY", "SG"] |
| preferredCountries | | ประเทศที่แสดงบนสุดของรายการ เช่น ["TH", "LA", "KH"] |
| search | true | ช่องค้นหาที่อยู่ด้านบน (แสดงเมื่อประเทศนั้นมีข้อมูลพื้นที่) |
| labels | | เปลี่ยนชื่อช่อง เช่น { level2: "เมือง/เขต" } |
| messages | | เปลี่ยนข้อความ เช่น { postalMismatch: "…" } |
| names | "auto" | อักษรของชื่อพื้นที่ "local" / "latin" แบบ auto จะใช้อักษรของประเทศนั้นเมื่อหน้าเว็บเป็นภาษาเดียวกับประเทศนั้น (ไทยเป็นภาษาไทย) กรณีอื่นใช้ละติน |
| showCountry | true | แสดงช่องเลือกประเทศ |
| showName, showOrganization | false | แสดงช่องชื่อผู้รับ / บริษัท |
| lines | 2 | จำนวนบรรทัดที่อยู่ 1–3 |
| showErrors | false | แสดง error ทุกช่องทันที (ใช้ตอนผู้ใช้กดส่ง) ถ้าฟอร์มอยู่ใน <form> การกดส่งจะถูกเบราว์เซอร์กันไว้และแสดง error ให้อยู่แล้ว |
| name | | ใส่แล้วทุกช่องมี name="<name>[field]" ส่งไปกับ <form> ได้ |
| disabled, className, style | | |
ใช้โดยไม่ต้องมี React (server, validation)
import {
getAddressFormat, validateAddress, validatePostalCode,
normalizePostalCode, formatAddress, loadCountryData,
} from "@inverz/world-address/core";
getAddressFormat("JP", { locale: "en" });
// { rows: [["postalCode"], ["level1", "level2"], ["line1"], ["line2"]],
// required: [...], labels: { level1: "Prefecture", ... }, postalCode: { pattern, example }, level1: [...] }
validatePostalCode("GB", "sw1a 2aa"); // true
normalizePostalCode("1500002", "JP"); // "150-0002"
validateAddress(address); // { valid, errors: { level1: "required", postalCode: "invalid" } }
validateAddress(address, { db }); // + ตรวจรหัสไปรษณีย์กับอำเภอ/ตำบล (ไทย)
findLevel1("US", "ca"); // { name: "California", code: "CA", … }
subdivisionCode(address); // "TH-10" (ISO 3166-2 เต็ม)
formatAddress(address); // ใช้พิมพ์ฉลากจัดส่ง แยกบรรทัดด้วย \n
formatAddress(address, { latin: true, country: "en" });
const db = await loadCountryData("US"); // null ถ้าไม่มีข้อมูลของประเทศนั้น
db.byPostalCode("94043"); // [{ level1, level2, level3, postalCode }]
db.level2(db.level1()[0].index); // เมืองในรัฐแรก
db.search(db.level2(), "san fr");
db.searchPlaces("hat yai"); // ค้นทั้งที่อยู่ พิมพ์ได้หลายคำ ทั้งไทยและอังกฤษ
level1ForPostalCode("US", "94043"); // [California] จากช่วงรหัสของ Google ไม่ต้องโหลดข้อมูลvalidateAddress ให้ error 3 แบบ: required ช่องบังคับว่าง, invalid รหัสไปรษณีย์ผิดรูปแบบ, mismatch รหัสถูกรูปแบบแต่ไม่อยู่ในรัฐ/จังหวัดที่เลือก (เช่น 94043 กับ Texas) ตรวจด้วยช่วงรหัสของแต่ละรัฐจาก Google รวมกับรหัสที่คร่อมเขตแดนจริงจากข้อมูล ถ้าส่ง db ของไทยไปด้วยจะตรวจถึงระดับอำเภอและตำบล
แปลงไป/กลับจากระบบอื่น
import {
toStripe, fromStripe, toShopify, fromShopify,
toSchemaOrg, fromSchemaOrg, toAutocomplete, fromAutocomplete,
fromGooglePlace,
} from "@inverz/world-address/core";
toStripe(address); // { line1, line2, city, state: "CA", postal_code, country }
fromGooglePlace(place); // ผลจาก Places API แบบใหม่ (addressComponents) หรือแบบเก่า (address_components)fromGooglePlace อ่านที่อยู่ไทยจากคำนำหน้าชื่อ (ตำบล/อำเภอ/จังหวัด, Tambon/Amphoe/Chang Wat, แขวง/เขต) จึงไม่ขึ้นกับชนิด component ที่ Google เปลี่ยนได้ ทดสอบกับรูปแบบตามเอกสารของ Google ยังไม่ได้ทดสอบกับผลจริงจาก API
ระบบที่ไม่มีระดับ 3 (Stripe, Shopify) จะรวม level3 ไว้ใน line2 ส่วน Schema.org รวมไว้หน้า addressLocality ("สีลม, บางรัก")
formatAddress จัดบรรทัดตามแบบของไปรษณีย์ประเทศนั้น ใช้ตัวพิมพ์ใหญ่ในช่องที่กำหนด ย่อชื่อรัฐแบบที่ใช้บนซองจดหมาย (California → CA) และใส่ ตำบล/อำเภอ/จังหวัด (แขวง/เขต ในกรุงเทพฯ) ให้ที่อยู่ไทย
Jane Doe 99/1 ถนนสีลม
1600 Amphitheatre Pkwy แขวงสีลม เขตบางรัก
MOUNTAIN VIEW, CA 94043 กรุงเทพมหานคร 10500
UNITED STATESธีม
override ตัวแปร --wad-brand, --wad-brand-soft, --wad-brand-strong, --wad-border, --wad-radius … (ดูหัวไฟล์ style.css) ถ้าไม่ได้ตั้งไว้จะใช้ค่าจาก --tdp-* ของ component อื่นของ Inverz
โหมดมืด: ใส่ data-theme="dark" ที่ <html> (หรือกล่องที่ครอบ) หรือใส่ class wad-dark ที่ฟอร์ม
การตรวจเมื่อกดส่ง
- ช่องบังคับใช้
requiredของ HTML และรหัสไปรษณีย์ที่ผิดรูปแบบหรือผิดพื้นที่ใช้setCustomValidityเมื่ออยู่ใน<form>เบราว์เซอร์จึงไม่ยอมส่ง และทุกช่องที่ผิดจะแสดงข้อความทันที - ถ้าจัดการการส่งเอง (ไม่มี
<form>) ให้ใช้validจากonChangeแล้วตั้งshowErrorsเมื่อผู้ใช้กดส่ง
const [check, setCheck] = useState({ valid: false });
const [submitted, setSubmitted] = useState(false);
<WorldAddressForm value={a} onChange={(next, v) => { setA(next); setCheck(v); }} showErrors={submitted} />
<button onClick={() => { setSubmitted(true); if (check.valid) save(a); }}>บันทึก</button>ขนาดแพ็กเกจและ /lite
ข้อมูลพื้นที่ 240 ประเทศแยกเป็นไฟล์ละประเทศ bundler (Vite, webpack, Next.js) จะสร้าง chunk ของแต่ละประเทศ ผู้ใช้โหลดเฉพาะประเทศที่เลือก แต่ build output ของแอปจะมีไฟล์ทั้ง 240 ไฟล์ (รวมประมาณ 20 MB) ถ้าไม่ต้องการ ใช้ /lite ซึ่งไม่มีไฟล์ข้อมูลในแอปเลย แล้วโหลดข้อมูลจาก CDN หรือ server ของตัวเอง:
import { WorldAddressForm, setCountrySource, cdnCountrySource } from "@inverz/world-address/lite";
setCountrySource(cdnCountrySource({ version: "1.0.0" })); // jsDelivr
// หรือ server ของตัวเอง (คัดลอก node_modules/@inverz/world-address/dist/countries/ ไปไว้)
setCountrySource((cc) => import(/* @vite-ignore */ `/address-data/${cc}.js`));ใช้ได้กับ
- React 16.9 ขึ้นไป (ทดสอบในเบราว์เซอร์กับ 17, 18 และ 19 และทดสอบ server-side rendering กับ 16.14)
- Vite, webpack 5, Next.js (App Router, ทั้ง Turbopack และ webpack) และ server-side rendering
- โค้ดใน
distเป็น ES2019 (ไม่มี?./??) ใช้กับ toolchain รุ่นเก่าได้ - TypeScript ทั้ง
moduleResolution: "bundler"และ"nodenext"
ข้อมูลและความครบถ้วน
| ข้อมูล | ครอบคลุม | ที่มา | |---|---|---| | รูปแบบที่อยู่ ช่องที่บังคับ ป้ายชื่อ รูปแบบรหัสไปรษณีย์ | 252 ประเทศ/ดินแดน | Google Address Data (CC-BY 4.0) | | รายชื่อรัฐ / จังหวัด (level1) | ทุกประเทศที่ที่อยู่ใช้ระดับนี้ | Google Address Data, GeoNames | | รหัส ISO 3166-2 ของรัฐ / จังหวัด | เติมส่วนที่ Google ไม่มี | Wikidata (CC0) | | เมือง/ตำบลพร้อมรหัสไปรษณีย์ | 108 ประเทศ | GeoNames postal codes (CC-BY 4.0) | | เมือง/อำเภอ (ไม่มีรหัสไปรษณีย์) | อีก 131 ประเทศ เช่น ลาว กัมพูชา เมียนมา เวียดนาม อินโดนีเซีย ซาอุดีอาระเบีย | GeoNames gazetteer: เขตการปกครองระดับ 2 หรือเมืองที่มีประชากร 500 คนขึ้นไป | | ประเทศไทย: 77 จังหวัด 928 อำเภอ 7,436 ตำบล ไทย/อังกฤษ | ครบ | @inverz/thai-address |
ข้อควรรู้:
- ความครบถ้วนต่างกันไปตามประเทศ สหรัฐฯ ญี่ปุ่น ฝรั่งเศส เยอรมนี เม็กซิโก มีข้อมูลละเอียด ส่วนบางประเทศมีแค่รหัสไปรษณีย์หลัก (บราซิล จีน) หรือไม่มีเลย ช่องทุกช่องจึงพิมพ์เองได้
- สหราชอาณาจักร แคนาดา และเนเธอร์แลนด์ มีแค่ส่วนต้นของรหัสไปรษณีย์ (
SW1A,K1A,1011) พิมพ์รหัสเต็มแล้วระบบจะใช้ส่วนต้นค้นให้ - ชื่อเมืองจาก GeoNames ส่วนใหญ่เป็นอักษรละติน (ญี่ปุ่นเป็น
Shibuya-kuไม่ใช่渋谷区) - ประเทศที่ไม่มีข้อมูลรหัสไปรษณีย์ พิมพ์รหัสแล้วจะเติมได้แค่รัฐ/จังหวัด (ถ้า Google มีช่วงรหัสของประเทศนั้น)
- เวียดนามปรับเขตการปกครองใหม่ในปี 2025 (รวมจังหวัดเหลือ 34 และยกเลิกระดับอำเภอ) ข้อมูลของ Google และ GeoNames ยังเป็นแบบเดิม
- ลาว กัมพูชา และเมียนมา: เพิ่มช่องจังหวัด/รัฐที่ Google ไม่ได้ใส่ไว้ เพื่อให้เลือกอำเภอตามจังหวัดได้
- แพ็กเกจหลักมีขนาดประมาณ 45 KB (gzip) ข้อมูลพื้นที่ทั้งหมดมีขนาดประมาณ 20 MB แต่แยกเป็นไฟล์ละประเทศ bundler จะสร้าง chunk ของแต่ละประเทศ และผู้ใช้จะโหลดเฉพาะประเทศที่เลือก (ไฟล์ที่ใหญ่ที่สุดคือเม็กซิโก ~1.1 MB gzip)
ถ้านำไปใช้ ต้องให้เครดิต Google และ GeoNames ตามสัญญาอนุญาต CC-BY 4.0 เช่นใส่ลิงก์ไว้ในหน้าเกี่ยวกับเราหรือ footer
อัปเดตข้อมูล: npm run fetch:data && npm run build:data หรือ GitHub Action Update address data ที่รันทุกต้นเดือนแล้วเปิด pull request ให้ตรวจ
License
MIT © 2026 Inverz Solutions Co.,Ltd. — ข้อมูลที่อยู่ © Google (CC-BY 4.0), รหัสไปรษณีย์ © GeoNames (CC-BY 4.0)
