🌍 countries-states-cities-service

The world's geographic data. Zero dependencies. Tree-shakable. TypeScript-first.

Why this package?

Every address form, user profile, and logistics app needs countries, states, and cities. Most solutions make you choose between incomplete data, bloated bundles, or heavy server-side calls.

This package gives you all three — fully offline, in one install:

| | | |---|---| | 🌐 250 countries | with ISO2, ISO3, phone codes, currencies, timezones & translations | | 🗺️ 4,868 states & regions | with coordinates and locale support | | 🏙️ 147,418 cities | filtered, sorted, and ready in milliseconds | | 📦 Zero runtime dependencies | fully self-contained | | 🌲 Tree-shakable | import only what you need — countries bundle is just 204 KB | | 🔷 TypeScript-first | full type definitions included | | ⚡ CJS + ESM | works everywhere: Node.js, React, Vue, React Native, Next.js | | ✅ 100% test coverage | no surprises in production |

Installation

npm install countries-states-cities-service
# or
pnpm add countries-states-cities-service
# or
yarn add countries-states-cities-service

Import — only pay for what you use

The package ships with subpath exports so bundlers and mobile frameworks (Metro, webpack, Vite) only include the data you actually import.

// Full package — all data
import { Countries, States, Cities } from 'countries-states-cities-service'

// Per-service — only loads what you need
import { Countries } from 'countries-states-cities-service/countries' // ~204 KB
import { States }    from 'countries-states-cities-service/states'    // ~584 KB
import { Cities }    from 'countries-states-cities-service/cities'    // ~6.5 MB

On React Native? Use the subpath imports. Your users will thank you.

Usage

Countries

import { Countries } from 'countries-states-cities-service'

// All countries
const countries = Countries.getCountries()

// Filter by ISO2 or ISO3
const italy = Countries.getCountries({ filters: { iso2: 'IT' } })
const usa   = Countries.getCountries({ filters: { iso3: 'USA' } })

// Multiple countries at once
const eu = Countries.getCountries({ filters: { iso2: ['IT', 'FR', 'DE', 'ES'] } })

// Localized names
const countries_it = Countries.getCountries({ locale: 'it' })

// Localized + filtered
const italy_it = Countries.getCountries({ filters: { iso2: 'IT' }, locale: 'it' })

// Sorted
const sorted = Countries.getCountries({ sort: { mode: 'alphabetical', key: 'name' } })

Supported locales: kr br pt nl hr fa de es fr ja it cn

interface Country {
  id: number
  name: string
  iso2: string
  iso3: string
  numeric_code: string
  phone_code: string
  capital: string
  currency: string
  currency_symbol: string
  tld: string
  native: string
  region: string
  subregion: string
  latitude: string
  longitude: string
  emoji: string
  emojiU: string
  timezones: Array<{
    zoneName: string
    gmtOffset: number
    gmtOffsetName: string
    abbreviation: string
    tzName: string
  }>
  translations: Partial<Record<TranslationLocale, string>>
}

States

import { States } from 'countries-states-cities-service'

// All states
const states = States.getStates()

// States by country
const it_states = States.getStates({ filters: { country_code: 'IT' } })

// Filter by multiple countries
const states = States.getStates({ filters: { country_code: ['IT', 'FR'] } })

// Single state by code
const liguria = States.getStates({ filters: { country_code: 'IT', state_code: 'GE' } })

// Italian regions only
const regions = States.getStates({ filters: { country_code: 'IT', is_region: true } })

// Localized state names
const states_it = States.getStates({ filters: { country_code: 'IT' }, locale: 'it' })

// Sorted
const sorted = States.getStates({ sort: { mode: 'alphabetical', key: 'name' } })

Cities

import { Cities } from 'countries-states-cities-service'

// All cities
const cities = Cities.getCities()

// Cities by country
const it_cities = Cities.getCities({ filters: { country_code: 'IT' } })

// Cities by multiple countries
const cities = Cities.getCities({ filters: { country_code: ['IT', 'FR'] } })

// Cities by country + state
const ligurian = Cities.getCities({ filters: { country_code: 'IT', state_code: '42' } })

// Sorted
const sorted = Cities.getCities({ sort: { mode: 'alphabetical', key: 'name' } })

Sort modes

All three services support the same sort options:

| Mode | Description | |------|-------------| | asc | Original order (default) | | desc | Reversed order | | alphabetical | Locale-aware alphabetical by any key |

{ sort: { mode: 'alphabetical', key: 'name' } }
{ sort: { mode: 'asc' } }
{ sort: { mode: 'desc' } }

Data source

Geographic data is sourced from dr5hn/countries-states-cities-database and bundled at build time — no network calls, no external API, no rate limits.

Contributing

Contributions are always welcome! Here's how:

1. Fork the repository
2. Create your branch: git checkout -b feat/my-improvement
3. Make your changes and add tests
4. Open a pull request — I review quickly

Support & feedback

Have a question or found a bug? Ping me on Twitter / X or open an issue.

License

MIT © Alessandro Casazza

Sponsor this project

This package is free and maintained in my spare time.
If it saves you hours of work, consider buying me a coffee ☕

Every sponsorship — no matter the size — keeps this project alive and growing.
Your name/logo can appear right here. Let's talk.