HTML Web Component

A framework-agnostic HTML Web Component (custom element) for Philippine barangay autocomplete search, powered by the GIS.PH API.

You can use it in plain HTML, React, Vue, Svelte, Angular, or any client-side environment that supports custom elements.

GitHub Repository: YahaayLabs/barangay-search

Installation

Install via your preferred package manager:

# Using npm
npm install barangay-search

# Using bun
bun add barangay-search

# Using pnpm
pnpm add barangay-search

Quick Start (Plain HTML)

Import the component as an ES module and add the <barangay-search> tag:

<script type="module" src="./node_modules/barangay-search/dist/barangay-search.js"></script>

<barangay-search api-key="YOUR_GIS_PH_API_KEY" placeholder="e.g. Poblacion Batangas"></barangay-search>

<script type="module">
  document.querySelector('barangay-search')
    .addEventListener('select', (e) => {
      console.log('Selected Barangay:', e.detail);
    });
</script>

Attributes & Properties

You can configure the component using either HTML attributes or JavaScript properties:

Property	Attribute	Type	Default	Description
apiKey	api-key	string	—	Your GIS.PH API Key (gis_sk_...). Sent in Authorization header.
accessToken	access-token	string	—	Alternative Bearer token.
placeholder	placeholder	string	Search barangay...	Input field placeholder text.
disabled	disabled	boolean	false	Disable the input control.
clearable	clearable	boolean	true	Show a clear button (×) when a barangay is selected.
debounceMs	debounce-ms	number	300	Search input debounce time in milliseconds.
minQueryLength	min-query-length	number	2	Minimum character length before triggering search query.
value	—	object | null	null	Property only. The currently selected barangay object.

Events

Custom events dispatched by the component bubble up and compose out of the Shadow DOM:

Event	detail Payload	Description
select	Barangay object	Dispatched when the user selects a barangay.
clear	null	Dispatched when the selection is cleared.
error	{ message: string }	Dispatched when an API or network error occurs.

Methods

You can call the following methods directly on the element instance:

• clear() — Clears the selected barangay and search input query.
• focus() — Focuses the inner input element.
• blur() — Blurs the inner input element.

Theming & Styling

The component uses Shadow DOM for style encapsulation, but can be themed using CSS Custom Properties (Variables):

barangay-search {
  --barangay-search-border: #e2e8f0;
  --barangay-search-radius: 8px;
  --barangay-search-focus: #3b82f6;
  --barangay-search-selected-bg: #f0fdf4;
}

CSS Shadow Parts

You can style specific parts of the component using the ::part() pseudo-element:

• ::part(input) — The text search input.
• ::part(list) — The floating results dropdown list.
• ::part(option) — The list option items.
• ::part(empty) — The “No results found” container.
• ::part(error) — The API error message container.
• ::part(clear) — The clear selection button.