address-react

@ph-dev-utils/address-react

React cascading Philippine address picker — region → province → city/municipality → ZIP, with ZIP autofill. Handles NCR (no provinces), independent cities, and multi-ZIP cities correctly.

npm install @ph-dev-utils/address-react

Component

import { PhAddressPicker, type AddressValue } from '@ph-dev-utils/address-react';
import '@ph-dev-utils/address-react/theme.css'; // optional styled preset

<PhAddressPicker
  onChange={(v: AddressValue) => console.log(v)}
  defaultValue={{ cityCode: '072217' }}  // optional: seed an edit form (region/province/zip auto-derived)
/>

Props

Prop	Type	Default	Notes
onChange	(v: AddressValue) => void	—	Fires on every change (not on mount)
defaultValue	{ regionCode?, provinceCode?, cityCode?, zip? }	—	Uncontrolled seed; cityCode alone hydrates the whole cascade
zipPolicy	'first' | 'none'	'first'	Autofill first candidate ZIP, or leave blank
showZip	boolean	true	Render the ZIP field
showBarangay	boolean	false	Render the barangay field (lazy-loads per city from jsDelivr)
searchable	boolean	false	Type-to-filter combobox for the long lists (city/municipality + barangay) instead of a native <select> — a province can hold 50+ municipalities
fetchBarangays	(cityMunCode) => Promise<{code,name}[]>	jsDelivr	Override the barangay source (self-host / mirror)
labels / placeholders	{ region?, province?, city?, barangay?, zip? }	English	For i18n / Tagalog
disabled required id className	—	—	Standard form props

AddressValue

interface AddressValue {
  region:   { code; name } | null;
  province: { code; name } | null;  // null is valid (NCR / independent cities)
  city:     { code; name; isCity } | null;
  barangay: { code; name } | null;  // v0.2
  zip: string | null;               // autofilled, user-overridable
  zipOptions: string[];             // all candidate ZIPs for the city
}

Hook

For custom UI, use the headless hook (same logic, your markup):

import { usePhAddress } from '@ph-dev-utils/address-react';

const { value, options, zipAmbiguous, selectRegion, selectProvince, selectCity, setZip, reset }
  = usePhAddress({ onChange, defaultValue });

Searchable (typeahead) fields

<PhAddressPicker searchable />

searchable swaps the city/municipality and barangay fields for an accessible type-to-filter combobox (WAI-ARIA combobox + listbox: arrow keys, Enter to select, Esc to revert, selection always resolved by PSGC code). Region and province stay native <select> since they are always short. The standalone Combobox is also exported if you want it elsewhere. Note: a combobox trades the native mobile picker wheel for searchability — leave it off (the default) if your audience is mostly mobile and your lists are short.

Styling

Ships unstyled with .ph-ap* class names. Import @ph-dev-utils/address-react/theme.css for a default PH-themed look, or target the classes yourself. The theme is recolorable via --ph-ap-* CSS custom properties. SSR-safe (useSyncExternalStore, no window/fetch at import). The theme covers the searchable combobox (.ph-ap__combobox, .ph-ap__listbox, .ph-ap__option).

Notes

• NCR hides the province step (province: null is valid). Independent cities (Isabela, Cotabato) are reachable in their region.
• Multi-ZIP cities (Manila ~200, Davao 12): the ZIP is autofilled but editable, with a candidate dropdown when zipAmbiguous. ZIP data is community-sourced (GeoNames), not an official PHLPost feed.
• Barangay (opt-in via showBarangay) lazy-loads a city's barangays from the jsDelivr CDN (@ph-dev-utils/address-data) — zero network unless enabled; optional, with a loading/error hint.

License

MIT (code). Bundled ZIP data © GeoNames, CC BY 4.0.