Official countries, states, and cities database with iOS/Safari support and minimal bundle size
npm install @countrystatecity/countriesOfficial countries, states, and cities database with iOS/Safari support and minimal bundle size.
- π Complete Data: 250+ countries, 5,000+ states, 150,000+ cities
- π± iOS Compatible: No stack overflow errors on Safari/iOS browsers
- π Minimal Bundle: <10KB initial load, lazy-load everything else
- π Lazy Loading: Dynamic imports for optimal performance
- π Translations: 18+ languages supported
- β° Timezone Data: Full timezone information per location
- π TypeScript: Full type definitions included
- π§ Tree-Shakeable: Only bundle what you use
``bash`
npm install @countrystatecity/countriesor
yarn add @countrystatecity/countriesor
pnpm add @countrystatecity/countries
`typescript
import { getCountries, getStatesOfCountry, getCitiesOfState } from '@countrystatecity/countries';
// Get all countries (lightweight - ~5KB)
const countries = await getCountries();
console.log(countries[0]);
// { id: 1, name: "United States", iso2: "US", emoji: "πΊπΈ", ... }
// Get all states in a country (~10-100KB depending on country)
const states = await getStatesOfCountry('US');
console.log(states[0]);
// { id: 1, name: "California", iso2: "CA", ... }
// Get all cities in a state (~5-200KB depending on state)
const cities = await getCitiesOfState('US', 'CA');
console.log(cities[0]);
// { id: 1, name: "Los Angeles", latitude: "34.05", ... }
`
#### getCountries()Promise
Get lightweight list of all countries (basic info only).
- Returns:
- Bundle Impact: ~5KB
#### getCountryByCode(countryCode: string)countryCode
Get full country metadata including timezones and translations.
- Parameters: - ISO2 code (e.g., 'US')Promise
- Returns:
- Bundle Impact: ~5KB per country
#### getStatesOfCountry(countryCode: string)countryCode
Get all states/provinces for a country.
- Parameters: - ISO2 codePromise
- Returns:
- Bundle Impact: ~10-100KB depending on country
#### getStateByCode(countryCode: string, stateCode: string)countryCode
Get specific state details.
- Parameters: , stateCodePromise
- Returns:
#### getCitiesOfState(countryCode: string, stateCode: string)countryCode
Get all cities in a specific state.
- Parameters: , stateCodePromise
- Returns:
- Bundle Impact: ~5-200KB depending on state
#### getAllCitiesOfCountry(countryCode: string)Promise
Get ALL cities in an entire country.
- Warning: Large data size, use sparingly
- Returns:
#### getAllCitiesInWorld()Promise
Get every city globally.
- Warning: MASSIVE data (8MB+), rarely needed
- Returns:
#### isValidCountryCode(countryCode: string)Promise
Check if country code exists.
- Returns:
#### isValidStateCode(countryCode: string, stateCode: string)Promise
Check if state code exists in a country.
- Returns:
#### searchCitiesByName(countryCode: string, stateCode: string, searchTerm: string)Promise
Search cities by partial name match.
- Returns:
#### getCountryNameByCode(countryCode: string)Promise
Get country name from code.
- Returns:
#### getStateNameByCode(countryCode: string, stateCode: string)Promise
Get state name from code.
- Returns:
#### getTimezoneForCity(countryCode: string, stateCode: string, cityName: string)Promise
Get timezone for specific city.
- Returns:
#### getCountryTimezones(countryCode: string)Promise
Get all timezones for a country.
- Returns:
`typescript`
import type { ICountry, ICountryMeta, IState, ICity, ITimezone } from '@countrystatecity/countries';
package (162K weekly downloads) has critical issues:
- π΄ 8MB bundle size (includes ALL data)
- π΄ iOS Safari crashes with stack overflow errors
- π΄ Unmaintained for 2+ years
- π΄ Static imports force entire bundle$3
- β
Minimal bundle (<10KB initial)
- β
Dynamic imports & lazy loading
- β
iOS/Safari compatible
- β
Always updated from authoritative database
- β
Tree-shakeable & code-splittableπ Bundle Size Comparison
| Action | @countrystatecity/countries | country-state-city |
|--------|----------------------------|-------------------|
| Install & import | 5KB | 8MB |
| Load countries | +2KB | - |
| Load US states | +30KB | - |
| Load CA cities | +15KB | - |
| Total for typical use | ~50KB | 8MB |
160x smaller bundle size!
π§ͺ Testing
`bash
Run all tests
npm testRun iOS compatibility tests specifically
npm run test:iosWatch mode
npm run test:watch
``This package and its data are licensed under the Open Database License (ODbL) v1.0. The data is sourced from the Countries States Cities Database which is also licensed under ODbL-1.0.
You are free to share, create, and adapt this database as long as you:
- Attribute: Credit the original sources
- Share-Alike: Distribute adaptations under the same license
- Keep Open: Don't use technical restrictions
Contributions are welcome! Please open an issue or PR.
For data-related issues (incorrect country names, missing cities, wrong coordinates, etc.), please report them to the Countries States Cities Database repository, which is the source of data for this package.
This package is part of the @countrystatecity ecosystem:
- @countrystatecity/countries - This package
- @countrystatecity/react - React components for country/state/city selection