Vue Barangay Search

A drop-in Vue 3 autocomplete search component for Philippine address forms, powered by the GIS.PH API.

Type free text like Poblacion Batangas, select a result, and bind a structured place object with v-model. Useful for checkout, KYC, registration, and delivery UIs.

GitHub Repository: YahaayLabs/vue-barangay-search

Installation

Install via your preferred package manager:

# Using bun (recommended)
bun add vue-barangay-search

# Using npm
npm install vue-barangay-search

# Using pnpm
pnpm add vue-barangay-search

Quick Start

<script setup>
import { ref } from 'vue'
import { BarangaySearch } from 'vue-barangay-search'
import 'vue-barangay-search/dist/vue-barangay-search.css'

const selectedBarangay = ref(null)
const apiKey = import.meta.env.VITE_GISPH_API_KEY // Get one at https://gis.ph
</script>

<template>
  <BarangaySearch
    v-model="selectedBarangay"
    :apiKey="apiKey"
    placeholder="Search for a barangay..."
    @select="(b) => console.log('Selected:', b)"
  />
</template>

Props

Prop	Type	Default	Description
apiKey	String	undefined	Recommended. Your API key (gis_sk_...) from gis.ph.
accessToken	String	undefined	Alternative authentication Bearer token. Used if apiKey is not set.
placeholder	String	Search barangay, city, or province...	Input placeholder text.
modelValue	Object	null	v-model binding for the selected barangay.
province	String	undefined	Optional: filter results to a specific province.
municipality	String	undefined	Optional: filter results to a specific municipality.

One of apiKey or accessToken is required for authenticated API access.

Events

Event	Payload	Description
update:modelValue	Object | null	Emitted when a selection is made or cleared.
select	Object	Emitted with the full barangay object on selection.
error	string	Emitted when an API or network error occurs.

Selection Shape

When a barangay is selected, v-model / @select receive the object returned by GET /v1/barangays/search. Use names, PSGC codes, or both.

{
  "id": 75322,
  "name": "Lahug",
  "municipality": "City of Cebu",
  "province": "Cebu",
  "region": "Region VII (Central Visayas)",
  "fullName": "Lahug, City of Cebu, Cebu, Region VII (Central Visayas)",
  "code": "0730600041",
  "lCode": "0730600000",
  "pCode": "0702200000",
  "rCode": "0700000000"
}

Field	Description
name	Barangay name
municipality	City or municipality name
province	Province name
region	Region name (e.g. Region VII, Negros Island Region)
fullName	Comma-joined label: barangay, LGU, province, region
code	Barangay 10-digit PSGC
lCode	City / municipality PSGC
pCode	Province PSGC
rCode	Region PSGC
id	Internal row id (stable for this dataset; prefer code for PSGC identity)

Dropdown rows show municipality, province, and region under the barangay name.

Local Demo

A playground directory is included in the package for testing:

bun install
cp .env.example .env.local   # Set VITE_GISPH_API_KEY=gis_sk_...
bun dev
# Opens playground at http://localhost:5173