Why Country/State/City Pickers Are Weirdly Hard

The article explains that implementing country, state, and city dropdown pickers is deceptively complex due to inconsistent data across regions (e.g., Singapore has no states, Turkey was renamed in 2022), API errors, and the need for search, caching, and keyboard navigation. After repeatedly rebuilding this feature, the author created the open-source npm package `react-country-state-city-picker`, which provides a ready-to-use React component with cascading logic, loading states, and headless hooks. The package is MIT licensed and available on GitHub, designed to be installed and used without further maintenance.

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 js 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 https://github.com/Shankulkarni/react-country-state-city-picker If you've rebuilt this before, you know what it's worth. Originally published at shankulkarni.com