\n\nBrowse the full 249-country dataset, run single and batch validations, and edit live code right in the browser โ no install required.\n\nPowered by Google's [`libaddressinput`](https://github.com/google/libaddressinput) โ the same dataset behind Chromium, Android, and Google Pay address forms.\n\n\nContents\n\n- [Quick start](#-quick-start)\n- [Why postal-code-checker?](#-why-postal-code-checker)\n- [Use cases](#-use-cases)\n- [API Reference](#-api-reference)\n- [Types](#๏ธ-types)\n- [Migration Guide](#-migration-guide)\n- [Roadmap](#๏ธ-roadmap)\n- [Data Sources](#-data-sources)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n\n\n---\n\n## โก Quick start\n\n```bash\nnpm install postal-code-checker\n```\n\n```ts\nimport { validatePostalCode, validatePostalCodes } from \"postal-code-checker\";\n\nvalidatePostalCode(\"US\", \"90210\"); // โ true\nvalidatePostalCode(\"CA\", \"k1a 0t6\"); // โ true (case + whitespace tolerant)\nvalidatePostalCode(\"GBR\", \"SW1A 1AA\"); // โ true (alpha-3 works too)\n\nvalidatePostalCodes(\"US\", [\"12345\", \"oops\"]); // โ [true, false]\n```\n\nWorks in **React, Next.js, Vue, Svelte, Angular, Node.js, Deno, Bun, and plain browser JS** โ no framework assumptions.\n\n---\n\n## ๐ก Why postal-code-checker?\n\nMost postal-code libraries ship a hand-written list of regexes. Someone typed\nthem in once, and they drift quietly as postal authorities change formats.\n\n**This one is generated, not typed.** Every pattern is regenerated from Google's\nfirst-party [`libaddressinput`](https://github.com/google/libaddressinput)\nAddress Data Service โ the dataset behind Chromium, Android, and Google Pay\naddress forms โ and the release is **blocked if the bundled data has drifted\nfrom upstream**. `src/assets/index.ts` carries a snapshot date, and\n`npm run sync:check` fails the publish if it is stale. The data is not a\none-time import; it is a build output with a provenance trail.\n\nThat is what the rest of the feature list rests on:\n\n- ๐ **249 countries** โ the full ISO 3166-1 alpha-2 and alpha-3 list, including\n the countries that have **no postal system at all**, where the correct answer\n is \"this field does not apply\" rather than a false rejection.\n- ๐ **Regenerated per release, drift-gated** โ a stale dataset cannot ship.\n- ๐ **Batch API** โ `validatePostalCodes(country, codes[])` returns an index-aligned `boolean[]`. Designed for CSV imports, bulk address uploads, and form arrays.\n- ๐งฉ **Extensible at runtime** โ `configure()` registers your own countries or\n overrides a bundled one. Codes outside ISO 3166-1 (Kosovo, internal region\n codes) work without forking the package.\n- ๐ **More than a boolean** โ `format()` returns the canonical storable form,\n `guessCountries()` infers candidates from a bare code.\n- ๐ค **Alpha-2 and alpha-3 both work** โ call with `\"US\"` or `\"USA\"`, `\"GB\"` or `\"GBR\"`. No branching at your call sites.\n- โจ **Forgiving input** โ case-insensitive and whitespace-tolerant. `\"k1a 0t6\"`, `\" K1A 0T6 \"`, and `\"K1A0T6\"` all validate equivalently where the country allows it.\n- ๐ชถ **Zero dependencies, TypeScript-first, dual ESM + CommonJS** โ bundled\n `.d.ts`, no `@types/*` install, `import` and `require()` both resolve through\n a strict `exports` map.\n- ๐ **Framework-agnostic** โ React, Next.js, Vue, Svelte, Angular, Node.js, Deno, Bun, plain browser JS.\n\n---\n\n## ๐งฉ Use cases\n\n\nEcommerce checkout โ validate ZIP before hitting your address API\n\n```ts\nimport { validatePostalCode } from \"postal-code-checker\";\n\nfunction onZipBlur(country: string, zip: string) {\n if (!validatePostalCode(country, zip)) {\n return \"Please check your postal code.\";\n }\n // safe to POST to /address-lookup\n}\n```\n\n\n\n\nReact Hook Form โ drop-in custom validator\n\n```tsx\nimport { useForm } from \"react-hook-form\";\nimport { validatePostalCode } from \"postal-code-checker\";\n\nconst { register } = useForm<{ country: string; postal: string }>();\n\n\n validatePostalCode(country, value) || \"Invalid postal code\",\n })}\n/>\n```\n\n\n\n\nCSV / bulk import sanity check โ batch API\n\n```ts\nimport { validatePostalCodes } from \"postal-code-checker\";\n\nconst rows = await parseCsv(\"./addresses.csv\");\nconst postals = rows.map((r) => r.postal);\nconst results = validatePostalCodes(\"US\", postals);\n\nconst bad = rows.filter((_, i) => !results[i]);\nconsole.log(`${bad.length} rows need review`);\n```\n\nBatch calls avoid N regex compiles โ one country lookup, N matches. Index-aligned output so you can zip results back to input rows.\n\n\n\n\nNext.js server action โ country-aware validation\n\n```ts\n\"use server\";\nimport { validatePostalCode } from \"postal-code-checker\";\n\nexport async function submitAddress(data: FormData) {\n const country = String(data.get(\"country\"));\n const postal = String(data.get(\"postal\"));\n if (!validatePostalCode(country, postal)) {\n return { error: \"Invalid postal code for that country\" };\n }\n // persistโฆ\n}\n```\n\n\n\n\nAddress autocomplete fallback โ when no API is available\n\n```ts\nimport { getCountryByCode } from \"postal-code-checker\";\n\nconst country = getCountryByCode(\"DE\");\n// country.examplePostalCodes โ [\"10115\"] โ use as placeholder\n// country.postalCodePatterns โ anchored regex strings, safe to render\n```\n\n\n\n---\n\n## ๐ API Reference\n\n### `validatePostalCode(countryCode, postalCode): boolean`\n\nValidates a single postal code against a country. Accepts both alpha-2 and alpha-3 ISO 3166-1 codes. Input is trimmed and uppercased before matching, so `\"k1a 0t6\"`, `\" K1A 0T6 \"`, and `\"K1A0T6\"` all validate equivalently where the country allows it.\n\n### `validatePostalCodes(countryCode, postalCodes): boolean[]`\n\nValidates an array of postal codes against one country and returns an index-aligned array of results. Unique to this package โ use it for CSV imports, bulk address uploads, and form arrays.\n\n### `format(countryCode, postalCode): string | null` โ _new in 2.1_\n\nReturns the canonical form of a valid postal code (trimmed, uppercased), ready to store in a database. Returns `null` when the input doesn't match the country's pattern or the country has no postal code system. Accepts alpha-2 and alpha-3.\n\n```ts\nformat(\"CA\", \"k1a 0t6\"); // โ \"K1A 0T6\"\nformat(\"US\", \" 12345 \"); // โ \"12345\"\nformat(\"US\", \"ABC12\"); // โ null\n```\n\n### `guessCountries(postalCode): CountryOption[]` โ _new in 2.1_\n\nGiven a postal code with no country context, returns every country whose pattern accepts the input. Sorted alphabetically by `countryName` โ ready to render as a picker. Countries with no postal code system are excluded.\n\n```ts\nguessCountries(\"K1A 0T6\");\n// โ [{ countryName: \"Canada\", countryCode: \"CA\" }]\n\nguessCountries(\"12345\");\n// โ [{ countryName: \"Algeria\", ... }, { countryName: \"Germany\", ... }, ...]\n```\n\n### `inferSubdivision(countryCode, postalCode): Subdivision[]` โ _new in 2.3_\n\nResolves a postal code to the state or province it belongs to โ for auto-filling a region field from a ZIP, offline, with no API call. The postal code is validated first, so an invalid code never returns a wrong guess. Always an array sorted by code: subdivision prefixes overlap, so some codes genuinely belong to more than one region.\n\n```ts\ninferSubdivision(\"US\", \"90210\"); // โ [{ code: \"CA\", name: \"California\" }]\ninferSubdivision(\"CA\", \"K1A 0T6\"); // โ [{ code: \"ON\", name: \"Ontario\" }, { code: \"QC\", name: \"Quebec\" }]\ninferSubdivision(\"US\", \"999999\"); // โ [] (not a valid US ZIP)\n```\n\n`code` is the ISO 3166-2 subdivision code without the country prefix (`\"CA\"`, not `\"US-CA\"`).\n\n### `getSubdivisions(countryCode): Subdivision[]` โ _new in 2.3_\n\nEvery subdivision the dataset knows for a country, sorted by code โ ready to render as a picker. `[]` when there is no data.\n\n### `hasSubdivisionData(countryCode): boolean` โ _new in 2.3_\n\nWhether subdivision data exists for a country. Use it to tell \"no data for this country\" apart from \"the code matched nothing\" โ both make `inferSubdivision` return `[]`.\n\n### `isInSubdivision(countryCode, postalCode, subdivision): boolean` โ _new in 2.3_\n\nWhether a postal code is valid **and** belongs to a specific subdivision (the unprefixed ISO 3166-2 code). Kept separate from `validatePostalCode` so consumers who only validate never bundle the subdivision dataset.\n\n```ts\nisInSubdivision(\"US\", \"90210\", \"CA\"); // โ true\nisInSubdivision(\"US\", \"90210\", \"NY\"); // โ false\n```\n\n### `getPostalLabel(countryCode): string` โ _new in 2.3_\n\nThe name a country uses for its postal code, for labelling a form field per country instead of showing \"ZIP code\" worldwide. Defaults to `\"postal code\"`.\n\n```ts\ngetPostalLabel(\"US\"); // โ \"ZIP code\"\ngetPostalLabel(\"IN\"); // โ \"PIN code\"\ngetPostalLabel(\"IE\"); // โ \"Eircode\"\ngetPostalLabel(\"DE\"); // โ \"postal code\"\n```\n\n> **Subdivision coverage.** The upstream dataset publishes subdivision postal prefixes for **24 of 249 countries** โ including the US, Canada, Brazil, India, Japan, Australia and Mexico, but **not** the UK, Germany, France or China. `inferSubdivision` returns `[]` for the rest; use `hasSubdivisionData()` to tell that apart from a validation failure. Subdivision data is tree-shaken out of the default import, so consumers who only validate pay nothing for it.\n\n### `getCountryByCode(countryCode): Country | null`\n\nReturns the full country record (patterns, example codes, name, 2-letter code) or `null` if unknown. Accepts alpha-2 or alpha-3. `postalCodePatterns` is a `string[]` โ most countries have one entry, some (e.g. GB with BFPO) have several.\n\n### `getAllCountries(): CountryOption[]`\n\nReturns `{ countryName, countryCode }[]` for every supported country, sorted alphabetically.\n\n### `configure(config): void` โ _new in 2.1_\n\nRegisters a user-supplied country dataset in one call, typically at app boot. Each entry either replaces a built-in country (when the alpha-2 key matches) or adds a brand-new country. Every utility in the package honors the override immediately โ no call-site changes needed.\n\n```ts\nimport { configure, validatePostalCode } from \"postal-code-checker\";\n\nconfigure({\n countries: {\n // Kosovo โ not in ISO 3166-1, so not in the bundled dataset\n XK: {\n patterns: [\"/^(?:[1-7]\\\\d{4})$/\"],\n example: [\"10000\", \"20000\"],\n country: \"Kosovo\",\n alpha3: \"XKX\",\n },\n },\n});\n\nvalidatePostalCode(\"XK\", \"10000\"); // โ true\nvalidatePostalCode(\"XKX\", \"10000\"); // โ true (alpha-3 works)\n```\n\nReplace semantics per country, idempotent across calls, and a fail-fast `ConfigurationError` on bad input. Full guide: [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md).\n\n> **SSR / multi-tenant:** `configure()` is a module-level singleton and isn't designed for per-request overrides. If you need that, [open an issue](https://github.com/sashiksu/postal-code-checker/issues/new) describing your use case.\n\n### `resetConfig(): void` โ _new in 2.1_\n\nDiscards any active `configure()` override and restores the bundled defaults. Primary use cases: test teardown (`afterEach(resetConfig)`), scenario switching, HMR.\n\n```ts\nafterEach(() => {\n resetConfig();\n});\n```\n\n### `usePostalCodeValidation()` โ _deprecated since 1.1.0_\n\nRetained for backward compatibility; delegates to the top-level `validatePostalCode`. Kept functional in 2.x; scheduled for removal in 3.0. Prefer the top-level exports in new code.\n\n---\n\n## ๐ท๏ธ Types\n\n```typescript\ntype CountryCode = string; // ISO 3166-1 alpha-2 (\"US\") or alpha-3 (\"USA\")\n\ntype AnyCountryCode = CountryCode | (string & {});\n// preserves autocomplete for known codes while accepting runtime-added ones\n\ntype Country = {\n postalCodePatterns: string[]; // regex strings wrapped in slashes, e.g. \"/^\\\\d{5}$/\"\n examplePostalCodes: string[];\n isGenericRegex: boolean;\n countryName: string;\n countryCode: AnyCountryCode;\n};\n\n// Shape accepted by configure()\ntype PostalCodeConfig = {\n countries: {\n [countryCode: string]: {\n patterns: string[]; // each entry wrapped in slashes, e.g. \"/^\\\\d{5}$/\"\n example: string[];\n country: string;\n alpha3?: string; // optional 3-letter uppercase alpha-3 code\n };\n };\n};\n```\n\n---\n\n## ๐ Migration Guide\n\n> **Coming from a different postal-code library?** See [`docs/SWITCHING.md`](./docs/SWITCHING.md) โ covers the common one-line equivalents, batch API migration, and the argument-order gotcha that trips most swaps.\n\n### From v1.x โ v2.0 (data-shape breaking change)\n\nv2.0 switches to Google's `libaddressinput` dataset and renames the regex field on the `Country` record. The runtime API (`validatePostalCode`, `validatePostalCodes`, `getCountryByCode`, `getAllCountries`) is unchanged โ but anything reading `country.postalCodeRegex` directly needs an update.\n\n**Before (v1.x):**\n\n```ts\nconst country = getCountryByCode(\"US\");\nconst regex = new RegExp(country.postalCodeRegex.slice(1, -1));\nregex.test(\"12345\");\n```\n\n**After (v2.0):**\n\n```ts\nconst country = getCountryByCode(\"US\");\nconst ok = country.postalCodePatterns.some((wrapped) =>\n new RegExp(wrapped.slice(1, -1)).test(\"12345\")\n);\n```\n\nIf you were only calling `validatePostalCode` / `validatePostalCodes`, nothing changes โ normalization and return types are identical.\n\n**Also note:**\n- `country.countryName` values follow Google's canonical spelling โ e.g. `\"United States\"` (was `\"United States of America\"`), `\"Russia\"` (was `\"Russian Federation\"`). Update any string pins in tests or UI copy.\n- A handful of previously-orphan alpha-3 codes (ร land, Martinique, Rรฉunion, Puerto Rico, etc.) now resolve correctly through `getCountryByCode`.\n\n### From `usePostalCodeValidation` (v1.0.x) โ `validatePostalCode` (v1.1.0+)\n\n```js\n// Before\nimport { usePostalCodeValidation } from \"postal-code-checker\";\nconst { validatePostalCode } = usePostalCodeValidation();\n\n// After\nimport { validatePostalCode } from \"postal-code-checker\";\n```\n\nThe `usePostalCodeValidation` name followed React's hook naming convention, which confused non-React users and tripped the `react-hooks/rules-of-hooks` lint rule even though it's not an actual hook. The new direct API works identically in React, Node.js, Vue, Angular, Svelte, or plain JavaScript.\n\n`usePostalCodeValidation` still exists in 2.x and delegates to the new implementation. Scheduled for removal in 3.0.\n\n---\n\n## ๐บ๏ธ Roadmap\n\n### โ Shipped\n\n- `inferSubdivision()` + `getSubdivisions()` + `hasSubdivisionData()` + `isInSubdivision()` โ resolve a postal code to its state/province from Google's `sub_zips` prefixes (24 countries) _(2.3.0)_\n- `getPostalLabel()` โ the name a country uses for its postal code, for per-country form labels _(2.3.0)_\n- `exports` map + native `.mjs` ESM build; `NOTICE` data license corrected to CC-BY 4.0 _(2.2.0)_\n- `configure()` + `resetConfig()` โ user-supplied country overrides and brand-new countries via a single-place config _(2.1.0)_\n- `format()` โ canonical storable form, or `null` if invalid _(2.1.0)_\n- `guessCountries()` โ countries whose pattern accepts an input _(2.1.0)_\n- Swap data source to Google `libaddressinput` _(2.0.0)_\n- Reproducible data pipeline โ `sync:data` + `sync:check` guard against upstream drift _(2.0.0)_\n- `postalCodePatterns: string[]` โ support countries with multiple valid patterns _(2.0.0)_\n- Interactive demo site at [sashiksu.github.io/postal-code-checker](https://sashiksu.github.io/postal-code-checker/) _(2.0.0)_\n- Full ISO 3166-1 coverage (249 countries, zero generic fallbacks) _(2.0.0)_\n- Batch validation (`validatePostalCodes`) _(1.1.0)_\n- Case + whitespace tolerant input _(1.1.0)_\n- ISO 3166-1 alpha-3 support _(1.1.0)_\n- Full unit-test coverage of utility functions _(1.1.0)_\n\n### ๐ Planned\n\n- `createValidator()` factory for SSR / multi-tenant use cases (if demand shows up)\n- Removal of deprecated `usePostalCodeValidation` _(3.0.0)_\n\n---\n\n## ๐ Data Sources\n\nPostal code patterns, country names, example codes, and subdivision prefixes come from Google's [`libaddressinput`](https://github.com/google/libaddressinput) project, fetched from `https://chromium-i18n.appspot.com/ssl-aggregate-address/data/`. The same dataset powers address forms in Chromium, Android, and Google Pay. `libaddressinput` licenses its source code under Apache-2.0 and its **data under CC-BY 4.0**; only the data is used here, so CC-BY 4.0 applies.\n\n`scripts/sync-postal-data.ts` regenerates `src/assets/index.ts` from upstream; `npm run sync:check` runs in CI and in `prepublishOnly` to block releases whose on-disk data has drifted from the script's output.\n\nSee [`NOTICE`](./NOTICE) for the upstream CC-BY 4.0 data attribution.\n\nPrior to v2.0.0, data was sourced from the European Central Bank (ECB), retrieved 4 Aug 2024.\n\n---\n\n## ๐ค Contributing\n\nPull requests welcome. See **[`CONTRIBUTING.md`](./CONTRIBUTING.md)** for local setup, the country-data workflow (upstream-first via `libaddressinput`), and maintainer sync steps.\n\nQuick start:\n\n1. Branch from `master`: `git checkout -b feature/` or `bugfix/`.\n2. Add or update tests under `src/__tests__/` for any behavior change.\n3. Follow existing style โ `npm run prettier` and `npm run lint` ship configs.\n4. Open a PR targeting `master`.\n\nFound a bug, missing country, or want to propose a feature? Use the [structured issue templates](./.github/ISSUE_TEMPLATE). For security issues, see [`SECURITY.md`](./SECURITY.md).\n\n---\n\n## ๐ License\n\n[MIT](./LICENSE)\n","readmeFilename":"README.md"}
![\"Validating](\"https://raw.githubusercontent.com/sashiksu/postal-code-checker/master/docs/hero.gif\")
\n![\"Launch](\"https://img.shields.io/badge/%F0%9F%9A%80%20%20Launch%20the%20Live%20Demo-171717?style=for-the-badge&labelColor=171717&color=ff6b35\"){kind=icon}