Getting Started

thaizip is a headless Thai address search library — zero runtime dependencies, no framework lock-in. This page walks through installing it and getting your first result.

Install

npm install thaizip

Requires Node.js 18 or later. React is an optional peer dependency — only needed if you want the useThaiAddressAutocomplete hook from thaizip/react. Without React, the core API works exactly the same.

Three entry points

The package splits into three entry points so you only import what you use:

import path	contents
thaizip	core functions + types (no React code, 4.4 KB gzip)
thaizip/react	useThaiAddressAutocomplete (ships "use client")
thaizip/data	loadDefaultIndex, clearDefaultIndex, getDefaultIndexIfLoaded (2.3 KB gzip + a 114 KB gzip data chunk fetched later)

thaizip/data is separated out because it’s by far the largest chunk — a tree-shaking bundler won’t pull it in unless you actually import it.

The dataset itself is split one level further, into its own emitted file. A bundler that code-splits dynamic imports (webpack, Turbopack, Vite/Rollup) will not download those 114 KB until loadDefaultIndex() actually runs — importing thaizip/data alone is not enough to pull them in. This is best-effort: bundlers or build modes that inline every dynamic import (some SSR/CJS setups) will still place it in the initial chunk.

Load the index and search

import { loadDefaultIndex } from 'thaizip/data'
import { searchThaiAddress, formatThaiAddressSuggestion, resolveThaiAddress } from 'thaizip'

const index = await loadDefaultIndex() // ~40ms of synchronous work, cached after

searchThaiAddress(index, 'ลาดพร้าว')
searchThaiAddress(index, 'bang rak')
searchThaiAddress(index, '10500')

loadDefaultIndex() loads all tambon/amphure/province data and builds an in-memory trigram index. The result is cached as a module-level singleton, so subsequent calls return the same index immediately without rebuilding it.

Performance tip

Call loadDefaultIndex() at mount time or when the route loads — don’t wait for the user’s first keystroke. Building the index costs roughly 40ms of synchronous main-thread work, and if that happens while the user is typing, it shows up as about 2 dropped frames.

Next steps

• Searching — searchThaiAddress options, result ranking, and known limitations
• Postal code lookup — how postal code search behaves, and why zipLimit is unlimited by default
• Cascade dropdowns — the province → district → subdistrict enumeration API
• English input — RTGS spellings and the supported alias list
• React Hook — useThaiAddressAutocomplete from thaizip/react
• Custom data — build an index from your own data with buildThaiAddressIndex
• Playground — try every searchThaiAddress option and see the results live