Every time I see this on a wireframe, I lie to myself.

"Yeah, that's easy."

Three dropdowns. Country → State → City.

Then three days disappear.

It starts innocent

Select a country, load states, select a state, load cities.

Then: Singapore has no states. Some countries call them provinces. Some APIs return empty arrays. A handful aren't in the dataset at all depending on which source you're pulling from.

Product wants search because nobody scrolls 195 countries on mobile. Then keyboard nav. Loading states. Error handling for when the city call fails mid-form. Caching so you're not hammering the API on every keystroke.

None of it is hard. It just keeps accumulating. By the third project you're copy-pasting code from your last one and hoping nothing changed. By the fifth you're a little angry.

The data is the actual problem

Country and city names feel stable until you work with them. Turkey officially became Türkiye in 2022. Cities get renamed. The Philippines has over 1,600 municipalities and that number moves. Some datasets recognize Kosovo. Others don't.

Most npm packages I tried were one of two things: a component sitting on a JSON file nobody had touched in two years, or solid current data with no UI layer at all.

Five rebuilds in, I stopped pretending this was handled.

What I built

I built react-country-state-city-picker.

Cascading logic, search, loading states, countries without states, keyboard nav, caching, dark/light mode. There's a single <CountryStateCityPicker> if you want the whole thing wired up, individual pickers if you only need one level, and headless hooks if you want your own UI. No dependencies outside React 18.

I wasn't trying to build something clever. I wanted a picker I could install and not think about again.

Quick start

npm install react-country-state-city-picker

import { CountryStateCityPicker } from 'react-country-state-city-picker'

function ShippingForm() {
  return (
    <CountryStateCityPicker
      onCountryChange={(country) => console.log(country)}
      onStateChange={(state) => console.log(state)}
      onCityChange={(city) => console.log(city)}
    />
  )
}

That's the basic setup. Individual pickers and custom render props are there if you need them.

Try it

MIT licensed, on GitHub: react-country-state-city-picker

If you've rebuilt this before, you know what it's worth.

Originally published at shankulkarni.com