jessebyarugaba/ug-address
Domain:
digital infrastructureRecord type:
software
Creator:
jes
Host:
Cascading Uganda address selector — District → County → Sub-county → Parish → Village. Single file, no dependencies, works offline.
# ug-address.js
A lightweight, dependency-free JavaScript library for cascading Uganda address selection.
**District → County/Division → Sub-county → Parish → Village**
Completely UI-agnostic — no CSS, no HTML, no framework dependencies, no DOM coupling. Use it with plain HTML, React, Vue, Svelte, Node.js, or any environment that runs JavaScript.
---
## Included Data
| Level | Records |
|---|---|
| Districts | 135 |
| Counties / Divisions | ~305 |
| Sub-counties | ~2,100 |
| Parishes | ~10,300 |
| Villages / Cells | ~71,200 |
---
## Features
- Single-file library — everything embedded, nothing to fetch
- No external datasets, no CORS issues, no async initialisation
- Works offline and with `file://`
- Fully event-driven with automatic downstream reset
- Works in the browser, Node.js, React, Vue, Svelte, Electron, and more
---
## Installation
### npm
```bash
npm install @jessebyarugaba/ug-address
```
### CDN (no install needed)
```html
```
```html
```
---
## Quick Start
```html
const addr = new UgAddress();
console.log(addr.getDistricts());
```
---
## Examples
- Plain HTML
- Node.js
- React
- Next.js
- Vue 3
- Svelte
- Alpine.js
- Python
- PHP
---
### Plain HTML
Full cascading example with five dropdowns wired together:
```html
const addr = new UgAddress();
function populate(el, items, placeholder) {
el.innerHTML = ' ' + placeholder + ' ';
items.forEach(function (item) {
const opt = document.createElement('option');
opt.value = item.id;
opt.textContent = item.name;
el.appendChild(opt);
});
el.disabled = items.length === 0;
}
const districtEl = document.getElementById('district');
const countyEl = document.getElementById('county');
const subcountyEl = document.getElementById('subcounty');
const parishEl = document.getElementById('parish');
const villageEl = document.getElementById('village');
const addressEl = document.getElementById('address');
populate(districtEl, addr.getDistricts(), 'Select Distri …