v1.0.7GitHub
THAI ADDRESS SELECT DOCUMENTATION

thai-address-select
Dropdown ที่อยู่ไทย

thai-address-select คือไลบรารี JavaScript/TypeScript สำหรับเลือก จังหวัด → อำเภอ/เขต → ตำบล/แขวง แบบเชื่อมโยง พร้อมค้นหารหัสไปรษณีย์จากข้อมูลในแพ็กเกจ ใช้กับ HTML select และ React ผ่าน bundler เช่น Vite

แพ็กเกจ v1.0.7 บน npm ↗ ผู้ดูแล ตรวจเอกสารกับ source

TSเขียนด้วย TypeScriptใช้กับ HTML select เดิมข้อมูลที่อยู่ในแพ็กเกจOpen source · MIT*

เหมาะกับฟอร์มจัดส่งสินค้า สมัครสมาชิก และข้อมูลลูกค้าที่ต้องเลือกที่อยู่ไทยแบบเป็นลำดับ ใช้ข้อมูลในแพ็กเกจโดยไม่ต้องมี API key; ไม่มีแผนที่ geocoding หรือช่อง autocomplete ในตัว

INTERACTIVE PLAYGROUND

ลองเลือกที่อยู่ดูสิLive demo

เลือกจังหวัด แล้วให้ dropdown ที่เหลือทำงานต่อให้คุณ

ที่อยู่จัดส่งตัวอย่างฟอร์ม
กำลังเตรียมเดโม...
หรือเริ่มจากที่อยู่ตัวอย่าง
ค่าที่ได้จาก getValue()
{
  "province": null,
  "district": null,
  "subDistrict": null,
  "zip_code": null
}

เดโมนี้ใช้ ThaiAddressSelect จาก source จริง · แสดงค่าที่ยังไม่เลือกเป็น null เพื่อให้อ่านง่าย (API คืน undefined)

77จังหวัด
929อำเภอ / เขต
7,451รายการตำบล / แขวง

นับจากไฟล์ข้อมูลใน repository นี้
ไม่ใช่การยืนยันข้อมูลเขตการปกครองล่าสุด

GETTING STARTED

ติดตั้ง thai-address-select ด้วย npm

ติดตั้งแพ็กเกจ แล้วนำเข้าในแอปฝั่ง browser ที่ใช้ bundler เช่น Vite

npm install thai-address-select
ใช้ bundler เพื่อจัดการ ES modules และ JSON

source นำเข้าฐานข้อมูล JSON โดยตรง และ entry point มี import ที่ไม่ระบุนามสกุล จึงไม่ควรเปิดไฟล์ HTML ผ่าน file:// หรือ import ไฟล์ใน dist ตรง ๆ ใน browser โดยไม่มี bundler

ต้องการรันเว็บเอกสารนี้บนเครื่อง?

ใช้ Node.js 22.12+ หรือ 24+ สำหรับเครื่องมือเว็บเอกสาร จากโฟลเดอร์ repository รัน:

Terminal · repository root
npm install
npm run docs:dev

# สร้างเว็บสำหรับนำไป host แบบ static
npm run docs:build
npm run docs:preview

npm run docs:build สร้างเว็บใน docs-dist/ และ npm run docs:preview เปิดดูผล build ส่วน npm run build ยังใช้ build ไลบรารีเหมือนเดิม

YOUR FIRST ADDRESS FORM

วิธีสร้าง Dropdown ที่อยู่ไทยด้วย JavaScript

ตัวอย่างนี้ใช้ JavaScript ในโปรเจคที่มี bundler และอ่านค่าทุกครั้งที่ฟอร์มเปลี่ยน

1

เตรียมช่องเลือกใน HTML

ใส่ id ให้แต่ละช่อง และใช้ readonly กับรหัสไปรษณีย์

index.html
<label for="province">จังหวัด</label>
<select id="province"></select>

<label for="district">อำเภอ / เขต</label>
<select id="district"></select>

<label for="subDistrict">ตำบล / แขวง</label>
<select id="subDistrict"></select>

<label for="zipCode">รหัสไปรษณีย์</label>
<input id="zipCode" readonly />

<script type="module" src="/main.js"></script>
2

สร้าง instance และเชื่อมกับฟอร์ม

นำเข้าไลบรารีใน main.js แล้วผูก element ทั้งสามเข้าด้วยกัน

main.js
import { ThaiAddressSelect, loadData } from "thai-address-select";

// ปัจจุบันข้อมูลพร้อมจาก import แล้ว
await loadData();

const address = new ThaiAddressSelect({
  provinceEl: document.getElementById("province"),
  districtEl: document.getElementById("district"),
  subDistrictEl: document.getElementById("subDistrict"),
});

const zipCode = document.getElementById("zipCode");
const updateZipCode = () => {
  zipCode.value = address.getValue().zip_code ?? "";
};

const events = [
  "provinceChange", "districtChange", "subDistrictChange"
];
events.forEach((event) => {
  address.addEventListener(event, updateZipCode);
});
updateZipCode();
3

รับที่อยู่พร้อมใช้ และคืนทรัพยากรเมื่อเลิกใช้

selectChange ส่งข้อมูลเมื่อเลือกครบสามช่อง ส่วนการเปลี่ยนจังหวัดหรืออำเภอจะรีเซ็ตช่องถัดไป จึงต้องอัปเดตรหัสไปรษณีย์จาก event รายช่องด้วย

main.js · ต่อจากตัวอย่างด้านบน
const onComplete = (event) => {
  console.log(event.detail);
  // { province: "กรุงเทพมหานคร", district: "เขตบางรัก",
  //   subDistrict: "สีลม", zip_code: "10500" }
};

address.addEventListener("selectChange", onComplete);

// เรียกเมื่อถอดฟอร์มหรือเปลี่ยนหน้าในแอปของคุณ
function cleanupAddressForm() {
  events.forEach((event) => {
    address.removeEventListener(event, updateZipCode);
  });
  address.removeEventListener("selectChange", onComplete);
  address.destroy();
}
MAKE IT YOURS

ตัวอย่าง React, Next.js และการปรับแต่งฟอร์ม

ตั้งค่าเริ่มต้น ปรับข้อความ หรือใช้แค่ฟังก์ชันค้นหาข้อมูลก็ได้

ปรับแต่งฟอร์ม

ใช้แทน main.js เดิมเพื่อกำหนด placeholder และที่อยู่เริ่มต้น พร้อมอัปเดตรหัสไปรษณีย์เมื่อผู้ใช้เปลี่ยนค่า

main.js · ใช้กับ HTML ในตัวอย่างเริ่มต้น
import { ThaiAddressSelect } from "thai-address-select";

const address = new ThaiAddressSelect({
  provinceEl: document.getElementById("province"),
  districtEl: document.getElementById("district"),
  subDistrictEl: document.getElementById("subDistrict"),
  placeholder: {
    province: "จังหวัดที่จัดส่ง",
    district: "เลือกอำเภอ / เขต",
    subDistrict: "เลือกตำบล / แขวง",
  },
  initialValue: {
    province: "กรุงเทพมหานคร",
    district: "เขตบางรัก",
    subDistrict: "สีลม",
  },
});

const sync = () => {
  document.getElementById("zipCode").value =
    address.getValue().zip_code ?? "";
};
const events = [
  "provinceChange", "districtChange", "subDistrictChange"
];
events.forEach((event) => address.addEventListener(event, sync));
sync(); // initialValue ไม่ส่ง event

function resetAddress() {
  address.setValue({});
  sync(); // setValue() ไม่ส่ง event เช่นกัน
}

function cleanupAddressForm() {
  events.forEach((event) => address.removeEventListener(event, sync));
  address.destroy();
}
ตั้งค่าผ่านโค้ดแล้ว อย่าลืมอ่านค่าใหม่

initialValue และ setValue() ไม่ส่ง event ให้เรียก getValue() เพื่ออัปเดต UI เอง และใช้ชื่อให้ตรงกับ dataset เช่น เขตบางรัก

THE REFERENCE

ThaiAddressSelect API: options, methods และ events

ชื่อและพฤติกรรมอ้างอิงจาก source ใน repository เวอร์ชัน v1.0.7

Constructor new ThaiAddressSelect(options)

Option Type การใช้งาน
provinceElrequired HTMLSelectElement ช่องเลือกจังหวัด
districtElrequired HTMLSelectElement ช่องเลือกอำเภอ / เขต
subDistrictElrequired HTMLSelectElement ช่องเลือกตำบล / แขวง
placeholder object · optional ข้อความ province, district, subDistrict ปรับแยกได้ ค่าเริ่มต้นคือ “เลือกจังหวัด”, “เลือกอำเภอ/เขต”, “เลือกตำบล/แขวง”
initialValue ThaiAddressValue · optional ชื่อจังหวัด อำเภอ และตำบลสำหรับค่าเริ่มต้น

Methods

getValue()

คืน { province?, district?, subDistrict?, zip_code? } เป็น string หรือ undefined รหัสไปรษณีย์ได้เมื่อเลือกครบและพบในข้อมูล

setValue(value)

เติมค่าตาม ThaiAddressValue โดยไม่ส่ง event ใช้ setValue({}) เพื่อล้างทั้งฟอร์ม ไม่ใช่การ merge ค่าเดิม

destroy()

ถอด listener ของไลบรารีออกจาก select ทั้งสามช่อง ไม่ลบ DOM และไม่ถอด listener ที่คุณเพิ่มเองบน instance

Events · CustomEvent.detail

Event ส่งเมื่อ detail
provinceChange ผู้ใช้เปลี่ยนจังหวัด { province }
districtChange ผู้ใช้เปลี่ยนอำเภอ { province, district }
subDistrictChange ผู้ใช้เปลี่ยนตำบล { province, district, subDistrict }
selectChange เลือกครบสามช่อง { province, district, subDistrict, zip_code }

Utility functions

นำเข้าจาก thai-address-select หรือ thai-address-select/utils โดยไม่ต้องสร้าง dropdown

Function ผลลัพธ์และพฤติกรรม
loadData() Promise<void> — ปัจจุบันข้อมูลโหลดผ่าน import แล้ว ฟังก์ชันนี้ resolve ทันที
getProvinces() string[] — ชื่อจังหวัดไม่ซ้ำ เรียงตามภาษาไทย
getDistricts(province) string[] — อำเภอในจังหวัด เรียงตามภาษาไทย ไม่พบคืน []
getSubDistricts(province, district) string[] — ตำบลในอำเภอ เรียงตามภาษาไทย ไม่พบคืน []
getzip_code(province, district, subDistrict) string | undefined — ชื่อฟังก์ชันใช้ตัว z เล็กตาม source
findProvinceByName(query) string[] — trim แล้วค้นหาข้อความที่อยู่ในชื่อด้วย includes ไม่ใช่ fuzzy matching; "" คืน [] แต่ช่องว่างล้วนคืนทุกจังหวัด

Types ที่ export: ThaiAddressSelectOptions และ ThaiAddressValue (ตัวหลังมีเฉพาะชื่อที่อยู่สามช่อง; return type ของ getValue() เพิ่ม zip_code)

UNDER THE HOOD

เล็กพอที่จะอ่านโค้ดตามได้

หน้าที่หลักแบ่งเป็นสามส่วน: ข้อมูล → ฟังก์ชันกรอง → ตัวควบคุม dropdown

JSONฐานข้อมูลที่อยู่thai-address.json
→
TSค้นหาและกรองfilterAddress.ts
→
DOMเชื่อม dropdownThaiAddressSelect.ts
Project structure
src/
├── index.ts                       # public exports และ types
├── components/
│   └── ThaiAddressSelect.ts        # DOM, state และ events
├── utils/
│   └── filterAddress.ts            # ฟังก์ชันค้นหาข้อมูล
└── data/
    └── thai-address.json           # จังหวัด → อำเภอ → ตำบล

dist/                              # ผล build ไลบรารี (tsc)
docs/                              # style, interaction และตัวอย่าง
index.html                         # เว็บเอกสารนี้
vite.config.mjs                    # config สำหรับเว็บเอกสาร
docs-dist/                         # ผล build เว็บ (ไม่ commit)
test.ts                            # ตัวอย่างทดลอง DOM ไม่ใช่ test runner

สิ่งที่ควรรู้จากการอ่านโปรเจค

  • ข้อมูลอยู่ใน bundle: JSON ต้นฉบับมีขนาดประมาณ 3.43 MB ก่อน minify และบีบอัด ไม่มีการเรียก API ที่อยู่ภายนอกตอนเลือก dropdown
  • จัดการ DOM โดยตรง: ใช้ document, EventTarget และ CustomEvent จึงควรสร้าง instance หลัง mount บน client
  • แยก build เว็บกับไลบรารี: tsc สร้าง JavaScript และ declarations ใน dist/; Vite bundle เว็บเอกสารไปที่ docs-dist/
  • ตรวจ packaging ก่อนนำไปเผยแพร่: package.json ยังระบุ dependency ชื่อเดียวกับแพ็กเกจตัวเอง และชี้ require ไปไฟล์ ESM จึงไม่รับรองการใช้ผ่าน CommonJS จากเว็บเอกสารนี้
  • ขอบเขตของข้อมูล: จำนวนบนหน้านี้นับรายการจากไฟล์จริงใน repository ไม่ใช่ข้อมูลเขตการปกครองล่าสุดที่ยืนยันโดยหน่วยงานภายนอก

แหล่งอ้างอิงของเอกสารและข้อมูล

พฤติกรรม API ตรวจจากโค้ดโดยตรง คุณตรวจสอบหรือแจ้งข้อมูลที่ควรแก้ได้จากแหล่งต่อไปนี้:

A FEW USEFUL ANSWERS

คำถามที่พบบ่อยเกี่ยวกับ thai-address-select

ค้นหารหัสไปรษณีย์ไทยโดยไม่สร้าง dropdown ได้ไหม?

ได้ ใช้ getzip_code(province, district, subDistrict) จาก thai-address-select/utils เช่น getzip_code("กรุงเทพมหานคร", "เขตบางรัก", "สีลม") ได้ "10500" หากชื่อไม่ตรงกับข้อมูลจะได้ undefined ดู ตัวอย่างฟังก์ชันข้อมูลที่อยู่

เป็นช่องพิมพ์ค้นหาที่อยู่แบบ autocomplete หรือไม่?

thai-address-select เป็น dropdown แบบเชื่อมโยงสามช่อง ไม่มีช่อง autocomplete ในตัว หากต้องการทำช่องค้นหาของตัวเอง ใช้ utility functions ดึงรายการไปสร้าง UI ได้ โดย findProvinceByName() ค้นหาชื่อจังหวัดที่มีข้อความตรงกัน ไม่ใช่ fuzzy search หรือการตรวจสอบที่อยู่จัดส่ง

ต้องใช้ API ภายนอกเพื่อค้นหารหัสไปรษณีย์ไหม?

ไม่ต้องเรียก API ที่อยู่ภายนอกตอนเลือกฟอร์ม เพราะ thai-address-select นำเข้าข้อมูลจังหวัด อำเภอ ตำบล และรหัสไปรษณีย์จาก JSON ในแพ็กเกจ ผ่าน bundler ของแอป ข้อมูลนี้ไม่ sync อัตโนมัติ

เปลี่ยนจังหวัดแล้วรหัสไปรษณีย์เก่ายังแสดงอยู่?

selectChange จะไม่ส่งเมื่อเลือกไม่ครบ ให้ฟัง provinceChange และ districtChange แล้วอ่าน getValue().zip_code ?? "" ใหม่ตามตัวอย่างเริ่มต้น

ทำไมเปิด index.html ตรง ๆ แล้วเดโมไม่ทำงาน?

เว็บนี้ต้องผ่าน Vite เพื่อแปลง TypeScript และ JSON ให้รัน npm install แล้ว npm run docs:dev จาก repository และเปิด URL ที่ terminal แสดง

ใช้กับ React หรือ Next.js ได้อย่างไร?

สร้าง instance ใน useEffect หลัง DOM พร้อม ใช้ dynamic import บน client และถอด listener พร้อมเรียก destroy() ตอน unmount ตัวอย่างในแท็บ React จัดการกรณี component ถูกถอดระหว่างโหลดด้วย

ตั้งค่าเริ่มต้นแล้วเลือกอำเภอหรือตำบลไม่ติด?

ชื่อต้องตรงกับข้อมูลและสัมพันธ์กันทั้งสามระดับ เรียก getDistricts(province) และ getSubDistricts(province, district) เพื่อดูชื่อจริง เช่นใช้ เขตบางรัก แทน บางรัก สำหรับอำเภอ

ปรับหน้าตาและปิดช่องที่ยังเลือกไม่ได้อย่างไร?

ไลบรารีใช้ select ของคุณ จึงแต่งด้วย CSS ได้ตามปกติ ส่วน disabled ต้องจัดการเองจากค่าปัจจุบัน เหมือนเดโมหน้านี้ที่เปิดช่องอำเภอหลังเลือกจังหวัด และเปิดช่องตำบลหลังเลือกอำเภอ

ข้อมูลจะอัปเดตให้อัตโนมัติไหม?

ไม่มีการ sync ข้อมูลภายนอก ข้อมูลผูกกับ JSON ในแพ็กเกจที่ติดตั้ง ควรตรวจสอบความเหมาะสมและความถูกต้องสำหรับงานของคุณก่อนใช้งานจริง

READY WHEN YOU ARE

ให้ฟอร์มถัดไป เลือกที่อยู่ได้ง่ายขึ้น

เริ่มด้วยสาม select แล้วต่อยอดในแบบของคุณ

สร้างฟอร์มแรก

ค้นหาเอกสาร

Tab เพื่อเลือกผลลัพธ์ · Enter เพื่อเปิด · Esc เพื่อปิด