Documentation · itzsa

Nepal Geo

Nepal administrative geography — provinces, districts, local levels (metropolitan, sub-metropolitan, municipality, rural municipality), and wards — with searchable React selects and a data-only package.

@itzsa/nepal-geo@itzsa/nepal-geo-data7 · 77 · 753 · ~6839en / ne

Installation#

UI package includes React selects. Install the data package alone when you only need queries.

pnpm add @itzsa/nepal-geo

pnpm add @itzsa/nepal-geo-data

@import "tailwindcss";
@source "../node_modules/@itzsa/nepal-geo";
@import "@itzsa/nepal-geo/styles.css";

Data helpers#

Queryable without mounting any UI. Same API on both packages.

import {
  getProvinces,
  getDistricts,
  getLocalLevels,
  getWards,
  getMetropolitanCities,
  getSubMetropolitanCities,
  getMunicipalities,
  getRuralMunicipalities,
  resolveLocalHierarchy,
} from "@itzsa/nepal-geo";
// Prefer data-only when you do not need React:
// import { … } from "@itzsa/nepal-geo-data";

getProvinces();
getDistricts(3);
getLocalLevels(27, { typeKeys: ["municipality", "rural_municipality"] });
getMetropolitanCities();
getSubMetropolitanCities();
getMunicipalities(27);
getRuralMunicipalities(27);
getWards(5);                 // Ward 1…N for a local
resolveLocalHierarchy(5, 12);

IDs

Values are numeric ids (provinceId, districtId, localId, wardId). Ward ids are localId * 1000 + number.

Data-only package#

Use @itzsa/nepal-geo-data when you do not need React selects.

pnpm add @itzsa/nepal-geo-data

import { getLocalLevels, getWards, GEO_META } from "@itzsa/nepal-geo-data";

// No React peer dependency — safe for Node, workers, APIs.

Local types & filters#

Filter to metropolitan, sub-metropolitan, municipality, or rural municipality.

type LocalLevelTypeKey =
  | "metropolitan"
  | "sub_metropolitan"
  | "municipality"
  | "rural_municipality";

// On selects:
<NepalLocalSelect typeKeys={["metropolitan", "sub_metropolitan"]} />
<NepalLocationSelect typeKeys={["municipality", "rural_municipality"]} />

Wards#

Ward lists are expanded from per-local counts — no huge static ward table.

import { getWards, encodeWardId } from "@itzsa/nepal-geo-data";

const wards = getWards(localId); // [{ id, localId, number, nameEn, nameNe }, …]
encodeWardId(5, 12); // → 5012

import { useState } from "react";
import {
  NepalLocationSelect,
  type NepalLocationValue,
} from "@itzsa/nepal-geo";
import "@itzsa/nepal-geo/styles.css";

export function AddressFields() {
  const [location, setLocation] = useState<NepalLocationValue>({});

  return (
    <NepalLocationSelect
      value={location}
      onChange={setLocation}
      levels={["province", "district", "local", "ward"]}
      labels={{ local: "Palika", ward: "Ward" }}
      locale="ne"
    />
  );
}

Examples#

Searchable selects — single level, cascade with wards, type filters, and custom CSS.

Single select#

label prop on each field; district waits until a province is chosen.

Province

District (scoped)

provinceId: — · districtId: —

Hierarchy + ward#

Province → district → local → ward. Changing a parent clears children.

प्रदेश

जिल्ला

स्थानीय तह

वडा

—

{}

Type filters#

Limit locals to urban types, then pick a ward.

District

Municipalities only

Ward

Dataset helpers: 6 metro · 276 municipalities · 460 rural · 0 wards for selection

Custom CSS#

vars and classNames without forking styles.css.

Styled province

Use vars and classNames — same pattern as the datepicker.

Locale#

English or Nepali labels from the same dataset.

प्रदेश

Dataset: 7 provinces · 77 districts · 753 local levels · 6839 wards

Sample: 7 / 77 loaded

Styling API#

Same pattern as @itzsa/nepali-datepicker.

<NepalProvinceSelect
  label="Province"
  vars={{ accent: "#0f766e", radius: "12px" }}
  classNames={{ trigger: "my-trigger", label: "my-label" }}
/>

classNames keys

root, trigger, label, popover, search, option, optionMeta, empty, clear, field, cascade

vars keys

accent, background, foreground, muted, border, surface, radius, font

Props API#

Full prop tables for selects and data helpers.

NepalGeoSelect (and Province / District / Local / Ward aliases)

Prop	Type	Default	Description
level	"province" \| "district" \| "local" \| "ward"	—	Which administrative level to list.
value	number \| null	null	Selected entity id. For wards, use encodeWardId(localId, n).
onChange	(id: number \| null) => void	—	Called when the selection changes or is cleared.
provinceId	number \| null \| undefined	—	Scope districts. null = wait for parent; omit/undefined = list all.
districtId	number \| null \| undefined	—	Scope local levels. null = wait for parent; omit = list all.
localId	number \| null \| undefined	—	Scope wards. null = wait for local; required for ward level.
typeKeys	LocalLevelTypeKey[]	—	Filter locals: metropolitan \| sub_metropolitan \| municipality \| rural_municipality.
label	string	—	Visible field label above the trigger.
locale	"en" \| "ne"	"en"	English (Outfit) or Nepali (Devanagari) labels.
placeholder	string	—	Trigger placeholder when nothing is selected.
vars	NepalGeoVars	—	CSS variable overrides (accent, border, radius, font, …).
classNames	NepalGeoClassNames	—	Slot class names: root, trigger, label, popover, option, …
clearable	boolean	true	Show Clear in the popover when a value is set.
showLocalType	boolean	true	Show local-level type as option meta (local level only).
disabled	boolean	false	Disable the control (also when waiting on a parent).

NepalLocationSelect

Prop	Type	Default	Description
value	NepalLocationValue	—	{ provinceId?, districtId?, localId?, wardId?, wardNumber? }
defaultValue	NepalLocationValue	—	Uncontrolled initial value.
onChange	(value: NepalLocationValue) => void	—	Fires on any step change; clearing a parent clears children.
levels	GeoLevel[]	["province","district","local","ward"]	Which steps to show, in order.
typeKeys	LocalLevelTypeKey[]	—	Filter the local-level step by type keys.
labels	Partial<Record<GeoLevel, string>>	—	Override the label above each field.
placeholders	Partial<Record<GeoLevel, string>>	—	Per-level placeholder strings.
locale	"en" \| "ne"	"en"	Locale for all cascade fields.
orientation	"vertical" \| "horizontal"	"vertical"	Stack fields or row layout from ~720px up.
vars / classNames	NepalGeoVars / NepalGeoClassNames	—	Shared styling applied to each field in the cascade.
clearable / disabled / showLocalType	boolean	—	Forwarded to each NepalGeoSelect in the cascade.

Data helpers (@itzsa/nepal-geo & @itzsa/nepal-geo-data)

Prop	Type	Default	Description
getProvinces / getDistricts / getLocalLevels	() => readonly T[]	—	List entities; districts/locals accept an optional parent id.
getLocalLevels(id, { typeKeys })	filter	—	Filter by metropolitan, municipality, rural, etc.
getMetropolitanCities	() => LocalLevel[]	—	Locals with type key metropolitan.
getSubMetropolitanCities	() => LocalLevel[]	—	Locals with type key sub_metropolitan.
getMunicipalities / getRuralMunicipalities	() => LocalLevel[]	—	Urban municipality and rural municipality helpers.
getWards(localId)	() => Ward[]	—	Expand ward count into Ward 1…N for a local level.
encodeWardId / decodeWardId	number helpers	—	Unique ward id = localId * 1000 + wardNumber.
resolveLocalHierarchy	(localId, wardNumber?) => …	—	Province + district + local + type (+ optional ward).