Installation
How to install and configure the Country State City package in your project.
Install
bash npm install @tansuasici/country-state-city Package entry points
The default entry resolves through conditional exports. Explicit browser and Node.js entry points are also available:
{
".": {
"types": "./countrystatecity-npm/dist/index.d.ts",
"browser": "./countrystatecity-npm/dist/index.browser.js",
"node": {
"import": "./countrystatecity-npm/dist/index.node.mjs",
"require": "./countrystatecity-npm/dist/index.node.cjs"
},
"default": "./countrystatecity-npm/dist/index.browser.js"
},
"./browser": {
"types": "./countrystatecity-npm/dist/index.d.ts",
"default": "./countrystatecity-npm/dist/index.browser.js"
},
"./node": {
"types": "./countrystatecity-npm/dist/index.d.ts",
"import": "./countrystatecity-npm/dist/index.node.mjs",
"require": "./countrystatecity-npm/dist/index.node.cjs"
}
}| Build | Format | Use Case |
|---|---|---|
index.browser.js | ESM | React, Next.js, Vite, Webpack |
index.node.mjs | ESM | Node.js with import |
index.node.cjs | CJS | Node.js with require |
Usage
import { CountryStateCity } from '@tansuasici/country-state-city';
// Get all countries
const countries = CountryStateCity.getAllCountries();
console.log(countries.length); // 250
// Get a specific country
const turkey = CountryStateCity.getCountryById(225);
console.log(turkey.name); // "Türkiye"
console.log(turkey.emoji); // "🇹🇷"
// Get states
const states = CountryStateCity.getStatesByCountryId(225);
console.log(states.length); // 81
// Get cities
const cities = CountryStateCity.getCitiesByStateId(2170); // Istanbul
console.log(cities[0].name); // City nameCountry flags in browser interfaces
The emoji field is a Unicode regional-indicator sequence. Whether it appears as a color flag or as
two letters depends on the operating system, browser, and installed emoji font. It is useful in text
output, but it is not a reliable UI asset.
For a consistent browser interface, resolve an image from the country iso2 value and host the
assets with your application:
function CountryFlag({ iso2, name }: { iso2: string; name: string }) {
const code = iso2.trim().toLowerCase();
return (
<img src={`/flags/${code}.svg`} width={24} height={18} alt={`${name} flag`} loading="lazy" />
);
}The Country State City website generates and serves its own 4:3 SVG set. The npm package does not expose those website assets as a package subpath, so applications should vendor an appropriately licensed flag set instead of hotlinking the live website.
Direct Data Access
Countries and states are available as full records. Cities use the documented compact distribution schema so the same 147,739-row dataset is not published twice:
import countries from '@tansuasici/country-state-city/data/countries.json' with { type: 'json' };
import states from '@tansuasici/country-state-city/data/states.json' with { type: 'json' };
import compactCities from '@tansuasici/country-state-city/data/cities.optimized.json' with { type: 'json' };
// { i: id, n: name, s: stateId, c: countryId, la: latitude, lo: longitude, w?: wikiDataId }
console.log(compactCities[0]);The full 89 MB canonical city source and large audit-evidence files are intentionally not copied
into the runtime package. Use the typed API when you need reconstructed full City records; use
the compact JSON export only when you explicitly want its short-key schema.