Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
compile
✓ import { compile } from 'country-states';
✗ const { compile } = require('country-states');
While CommonJS `require` can be used in older Node.js environments, ESM `import` is the preferred and more idiomatic way to load this module in modern JavaScript and TypeScript projects. The `compile` function must be called once with desired country codes before state data can be accessed.
states
✓ import { states } from 'country-states';
✗ const { states } = require('country-states');
The `states` function retrieves the list of subdivisions for a specific country. It is essential that the target country's data has been initialized via a preceding call to `compile`.
default import
✓ import * as countryStates from 'country-states';
✗ import countryStates from 'country-states';
This package exports named symbols (`compile`, `states`) and does not provide a default export. Attempting a default import will result in `undefined` or an error, as there's no top-level default export.
This quickstart demonstrates how to initialize country data using `compile` and then retrieve specific state information using `states`, highlighting the importance of pre-compilation for desired country codes.
import { compile, states } from 'country-states';
// It's crucial to call `compile` with the country codes you intend to use
// before attempting to retrieve states. This initializes the data for those countries.
// ISO 3166-1 alpha-2 codes are used here.
compile(['US', 'CA', 'DE', 'AU']);
console.log('States for United States (US):');
const usStates = states('US');
if (usStates && usStates.length > 0) {
console.log(` Total US states/territories: ${usStates.length}`);
console.log(' First 3 US states:', usStates.slice(0, 3).map(s => s.name).join(', '));
} else {
console.log(' No data found for US.');
}
console.log('\nStates for Germany (DE):');
const deStates = states('DE');
if (deStates && deStates.length > 0) {
console.log(` Total German states/territories: ${deStates.length}`);
console.log(' First 3 German states:', deStates.slice(0, 3).map(s => s.name).join(', '));
} else {
console.log(' No data found for DE. Did you include it in compile()?');
}
// Attempting to access a country not compiled will return undefined or an empty array.
console.log('\nStates for France (FR) without prior compilation:');
const frStates = states('FR');
if (frStates && frStates.length > 0) {
console.log(` Total FR states/territories: ${frStates.length}`);
} else {
console.log(' No data found for FR, as it was not included in compile().');
}
// You can inspect the structure of a state object
if (usStates && usStates.length > 0) {
console.log('\nExample state object (from US):', usStates[0]);
}
Errors
Common errors & fixes
TypeError: states is not a function
Incorrect import or require statement, or trying to access `states` before the module is properly loaded.
fixUse `import { states } from 'country-states';` for ESM or `const { states } = require('country-states');` for CJS. Verify the package is correctly installed via `npm install country-states`. console.log(states('XX')) returns undefined or an empty array
The country code 'XX' was not included in the array passed to the `compile` function, or the `compile` function was not called at all.
fixBefore calling `states('XX')`, ensure you have executed `compile(['XX', ...])` with 'XX' explicitly listed in the array of country codes. Cannot find module 'country-states'
The package has not been installed or is not correctly resolved in your project's `node_modules`.
fixRun `npm install country-states` or `yarn add country-states` in your project directory.
Audit
Dependencies
No dependency data recorded yet.