Nepali Address Picker

A React component for selecting Nepali addresses with cascading dropdowns. This component allows users to select a province, then a district, and finally a local body (municipality, metropolitan, rural municipality, or sub-metropolitan).

🌟 Features

• 🗺️ Cascading Dropdowns: Province → District → Local Body
• 🇳🇵 Nepali Language Support: Option to display names in both English and Nepali
• 🎯 Default & Controlled Values: Pre-populate or fully control selections with value prop
• 🎨 Modern Built-in Styling: No external CSS needed, fully responsive
• 📏 Customizable Layout & Size: Horizontal/vertical layout, customizable select width/height
• 📱 Responsive Design: Works on desktop and mobile devices
• 🌙 Dark Mode Support: Automatic dark mode detection
• 📦 TypeScript Support: Full TypeScript definitions included
• 🔧 Utility Functions: Helper functions for data access and filtering

📦 Installation

npm install nepali-address-picker

🚀 Quick Start

Basic Usage (No Default Value)

import { useState } from 'react';
import { NepaliAddressPicker } from 'nepali-address-picker';

function App() {
  const [selectedAddress, setSelectedAddress] = useState({
    province: '',
    district: '',
    localBody: ''
  });

  const handleAddressChange = (address: any) => {
    setSelectedAddress({
      province: address?.province?.Provinces || address?.province || '',
      district: address?.district?.Name || address?.district || '',
      localBody: address?.localBody?.Name || address?.localBody || ''
    });
  };

  return (
    <NepaliAddressPicker
      value={selectedAddress}
      onAddressChange={handleAddressChange}
    />
  );
}

With Default Value (Controlled)

const DEFAULT_ADDRESS = {
  province: 'Bagmati',
  district: 'Kathmandu',
  localBody: 'Kathmandu'
};

function App() {
  const [selectedAddress, setSelectedAddress] = useState(DEFAULT_ADDRESS);
  // ...
  return (
    <NepaliAddressPicker
      value={selectedAddress}
      onAddressChange={handleAddressChange}
    />
  );
}

🆕 Customization

Layout (Horizontal or Vertical)

<NepaliAddressPicker layout="horizontal" ... /> // horizontal
<NepaliAddressPicker layout="vertical" ... />   // vertical (default)

Select Size

<NepaliAddressPicker selectWidth="300px" selectHeight="48px" ... />

Placeholders

<NepaliAddressPicker
  placeholder={{
    province: 'Select Province',
    district: 'Select District',
    localBody: 'Select Local Body'
  }}
  ...
/>

Built-in Modern Styling

• No need to import any CSS file manually.
• The component is fully styled and responsive out of the box.
• You can override select size via props or with CSS variables:

  .nepali-address-picker {
    --address-select-width: 250px;
    --address-select-height: 40px;
  }

🔧 API Reference

Props

| Prop | Type | Default | Description | |-----------------|----------------------------------------------------------------------|--------------|----------------------------------------------------------| | onAddressChange | (address: AddressData) => void | - | Callback function called when address selection changes | | value | AddressData \| { province?: string; district?: string; localBody?: string } | - | Controlled value for the picker | | defaultValues | { province?: string; district?: string; localBody?: string } | - | (Uncontrolled) Default values to pre-populate selections | | showNepali | boolean | false | Whether to show Nepali names alongside English names | | className | string | '' | Additional CSS class for styling | | placeholder | { province?: string; district?: string; localBody?: string } | Default placeholders | Custom placeholder text for each dropdown | | layout | 'vertical' \| 'horizontal' | 'vertical' | Layout of the dropdowns | | selectWidth | string | 100% | Width of the select elements (e.g., '300px', '100%') | | selectHeight | string | 44px | Height of the select elements (e.g., '48px', '2.5rem') |

Types

AddressData

interface AddressData {
  province: ProvinceInfo | null;
  district: DistrictInfo | null;
  localBody: MunicipalityInfo | MetropolitanInfo | RuralMunicipalityInfo | SubMetroInfo | null;
}

ValueAddress (for value prop)

// You can use either AddressData or this simple object:
{
  province?: string;
  district?: string;
  localBody?: string;
}

🎨 Styling

• Modern, responsive styling is built-in.
• Customize select size via selectWidth and selectHeight props or CSS variables.
• No external CSS import required.

📊 Data Coverage

The component uses official Nepali administrative data including:

• 7 Provinces: All Nepali provinces
• 77 Districts: All districts across provinces
• 293 Municipalities: Regular municipalities
• 6 Metropolitan Cities: Major metropolitan areas
• 460 Rural Municipalities: Rural administrative areas
• 11 Sub-Metropolitan Cities: Sub-metropolitan areas

🌐 Browser Support

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

🤝 Contributing

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

📄 License

This project is licensed under the ISC License.

👨‍💻 Author

Manish Kumar Rajak

🆘 Support

If you encounter any issues or have questions, please open an issue on the GitHub repository.

🔗 Related

• Nepal Administrative Divisions
• React Documentation
• TypeScript Documentation