🇮🇳 India State District

Note: This is an educational project designed to demonstrate Indian geographical data handling. Feel free to use it for learning purposes.

A lightweight, type-safe TypeScript utility package for handling Indian states and districts data.

Overview

India State District is a zero-dependency solution that provides comprehensive data and utility functions for handling Indian geographical data (states and districts). Built with TypeScript, it offers a type-safe and developer-friendly way to work with Indian geographical data in your applications.

Features

• ✨ Type Safety - Built with TypeScript for enhanced developer experience and code reliability
• 🚀 Zero Dependencies - Lightweight implementation with no external dependencies
• 📦 Tree-Shakeable - Import only what you need
• 🔄 Utility Functions - Comprehensive set of functions for data manipulation
• 🎯 Framework Agnostic - Use with any JavaScript framework or vanilla JS
• 🛡️ Modern Browsers - Full support for all modern browsers

Installation

1# Using npm
2npm install india-state-district
3
4# Using yarn
5yarn add india-state-district
6
7# Using pnpm
8pnpm add india-state-district

Usage

Basic Usage (Recommended)

1import india, {
2  getAllStates,
3  getDistricts,
4  getAllStateCodes,
5  getCurrentState,
6  getAllStatesWithDistricts,
7} from "india-state-district"
8
9// Get all states
10const states = getAllStates()
11
12// Get districts for a specific state code
13const districts = getDistricts("MH")
14
15// Get all state codes
16const codes = getAllStateCodes()
17
18// Get current state (from default instance)
19const currentState = getCurrentState()
20
21// Get all states with their districts
22const allStatesWithDistricts = getAllStatesWithDistricts()

Advanced Usage (Custom Instance)

1import {
2  createIndiaStateDistrict,
3  IndiaStateDistrict,
4} from "india-state-district"
5
6const customIndia = createIndiaStateDistrict()
7
8// Use methods on the custom instance
9const states = customIndia.getAllStates()
10const districts = customIndia.getDistrictsForState("MH")

Node.js/CommonJS Usage

1const india = require("india-state-district").default
2const { getAllStates, getDistricts } = require("india-state-district")
3
4console.log(getAllStates())
5console.log(getDistricts("MH"))

React Example

1import React, { useState } from "react"
2import { getAllStates, getDistricts } from "india-state-district"
3
4const LocationSelector: React.FC = () => {
5  const [selectedState, setSelectedState] = useState("")
6  const [selectedDistrict, setSelectedDistrict] = useState("")
7  const [districts, setDistricts] = useState<string[]>([])
8
9  const handleStateChange = (state: string) => {
10    setSelectedState(state)
11    setDistricts(getDistricts(state))
12    setSelectedDistrict("")
13  }
14
15  return (
16    <div>
17      <select
18        value={selectedState}
19        onChange={(e) => handleStateChange(e.target.value)}
20      >
21        <option value=''>Select State</option>
22        {getAllStates().map((state) => (
23          <option key={state.code} value={state.code}>
24            {state.name}
25          </option>
26        ))}
27      </select>
28
29      <select
30        value={selectedDistrict}
31        onChange={(e) => setSelectedDistrict(e.target.value)}
32        disabled={!selectedState}
33      >
34        <option value=''>Select District</option>
35        {districts.map((district) => (
36          <option key={district} value={district}>
37            {district}
38          </option>
39        ))}
40      </select>
41    </div>
42  )
43}
44
45export default LocationSelector

API Reference

Default Instance Utility Functions

Function	Description	Arguments	Returns
getAllStates()	Get all states	None	State[]
getDistricts(stateCode)	Get districts for a state code	stateCode: string	string[]
getAllStateCodes()	Get all state codes	None	string[]
getCurrentState()	Get current state (from default instance)	None	State
getAllStatesWithDistricts()	Get all states with their districts	None	Array<{ state: State, districts: string[] }>

Factory & Class

• createIndiaStateDistrict() — Create a new instance for advanced use-cases
• IndiaStateDistrict — Class for advanced usage

Types & Flag Utilities

• State, StateData — TypeScript types
• INDIA_FLAG_SVG, INDIA_FLAG_COLORS, getIndiaFlagSVG, getIndiaFlagDataUrl — Flag utilities

Browser Support

The package is tested and supported on all modern browsers:

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)
• Opera (latest)

Changelog

See CHANGELOG.md for a list of changes and version history. We follow Semantic Versioning and document all notable changes following the Keep a Changelog format.

Contributing

We appreciate all contributions to improve India State District. Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/enhancement)
3. Make your changes
4. Commit (git commit -m 'Add enhancement')
5. Push to the branch (git push origin feature/enhancement)
6. Open a Pull Request

Please ensure your PR adheres to the following guidelines:

• Follow the existing code style
• Add tests for new features
• Update documentation as needed
• Keep commits atomic and well-described

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• ⭐ Star this repository
• 🐛 Report issues
• 🤝 Submit pull requests
• 📢 Share with others

---

Developed with ❤️ by Suraj Aswal

Report Bug · Request Feature