Country States Database

Common errors

• TypeError: states is not a function

  cause Incorrect import or require statement, or trying to access `states` before the module is properly loaded.
  fix Use `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

  cause The country code 'XX' was not included in the array passed to the `compile` function, or the `compile` function was not called at all.
  fix Before calling `states('XX')`, ensure you have executed `compile(['XX', ...])` with 'XX' explicitly listed in the array of country codes.

• Cannot find module 'country-states'

  cause The package has not been installed or is not correctly resolved in your project's `node_modules`.
  fix Run `npm install country-states` or `yarn add country-states` in your project directory.

Warnings

• gotcha The `compile` function must be called with an array of ISO 3166-1 alpha-2 country codes before attempting to retrieve states for those countries. Calling `states()` for an uncompiled country will return `undefined` or an empty array.
  Fix: Ensure `compile(['US', 'DE', ...])` is executed once at application startup or before any `states()` calls for relevant countries.
• breaking As a package with a version number below 1.0.0, `country-states` does not guarantee API stability. Minor versions may introduce breaking changes without adhering to semantic versioning until a stable 1.x release.
  Fix: Pin exact versions (e.g., `"country-states": "0.0.10"`) in `package.json` and manually test upgrades before deployment.
• gotcha The completeness and accuracy of country/state data are dependent on the package's maintenance and upstream ISO 3166-2 updates. Some subdivisions might be missing or outdated.
  Fix: For critical applications, cross-reference data with official ISO sources or governmental APIs to ensure accuracy and up-to-dateness.

Install

• npm install country-states npm
• yarn add country-states yarn
• pnpm add country-states pnpm

Imports

• compile
  wrong:

  const { compile } = require('country-states');

  correct:

  import { compile } from '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
  wrong:

  const { states } = require('country-states');

  correct:

  import { states } from '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
  wrong:

  import countryStates from 'country-states';

  correct:

  import * as 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.

Quickstart

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]);
}