Country State Dropdown


A lightweight, easy-to-use package for retrieving country and state/region data with optional React dropdown components.

Features

- 🌎 Comprehensive list of countries and their states/regions
- 🔍 Simple API to fetch countries and corresponding states
- ⚛️ Ready-to-use React dropdown components
- 🪶 Lightweight with zero dependencies
- 🛠️ Fully customizable styling options
- 📦 ESM support

Installation

``bash
npm install country-state-dropdown
`

or

`bash
yarn add country-state-dropdown
`

Usage

$3

`javascript
import {
getAllCountries,
getStatesByCountryCode,
} from "country-state-dropdown";

// Get all countries (returns array of objects with name and code)
const countries = getAllCountries();
// Example output: [{ name: "United States", code: "US" }, { name: "Canada", code: "CA" }, ...]

// Get states for a specific country by country code
const usStates = getStatesByCountryCode("US");
// Example output: ["California", "Texas", "New York", ...]
`

$3

`jsx
import { CountryDropdown, StateDropdown } from "country-state-dropdown";

function LocationForm() {
const [country, setCountry] = useState("");
const [state, setState] = useState("");

return (


`jsx
className="my-custom-dropdown"
style={{ width: "100%", padding: "8px" }}
/>
`

API Reference

$3

| Function | Parameters | Return Value | Description |
| ------------------------------ | -------------- | ------------------------------------- | --------------------------------------------------------------------- |
| getAllCountries() | None | Array<{name: string, code: string}> | Returns all countries with their names and 2-letter ISO country codes |
| getStatesByCountryCode(code) | code: string | Array | Returns array of state/region names for the specified country code |

$3

#### CountryDropdown

| Prop | Type | Required | Description |
| -------- | -------- | -------- | ----------------------------------------------------------------------- |
| value | string | No | The selected country code |
| onChange | function | Yes | Handler function that receives the selected country code as an argument |

#### StateDropdown

| Prop | Type | Required | Description |
| ----------- | -------- | -------- | ---------------------------------------------------------------- |
| countryCode | string | Yes | The country code to load states for |
| value | string | No | The selected state |
| onChange | function | Yes | Handler function that receives the selected state as an argument |
| disabled | boolean | No | Automatically disabled when no countryCode is provided |

Supported Countries

Currently includes 20+ countries with their states/regions, including:

- 🇺🇸 United States
- 🇨🇦 Canada
- 🇬🇧 United Kingdom
- 🇦🇺 Australia
- 🇩🇪 Germany
- 🇫🇷 France
- 🇮🇳 India
- 🇯🇵 Japan
- 🇳🇬 Nigeria
- 🇧🇷 Brazil
- 🇨🇳 China
- 🇷🇺 Russia
- 🇿🇦 South Africa
- _and many more..._

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

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 MIT License - see the LICENSE file for details.

Author

Dennis Temoye