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

npm install country-state-dropdown

or

yarn add country-state-dropdown

Usage

Basic Data API

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", ...]

React Components

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

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

  return (
    <form>
      <div>
        <label htmlFor="country">Country</label>
        <CountryDropdown
          value={country}
          onChange={(value) => setCountry(value)}
        />
      </div>

      <div>
        <label htmlFor="state">State/Province</label>
        <StateDropdown
          countryCode={country}
          value={state}
          onChange={(value) => setState(value)}
        />
      </div>
    </form>
  );
}

Styling

Both dropdown components accept standard HTML attributes, including className for custom styling:

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

API Reference

Data Functions

| 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<string> | Returns array of state/region names for the specified country code |

React Components

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