{"id":16609,"library":"country-states","title":"Country States Database","description":"The `country-states` package provides a lightweight, focused database containing country and state/subdivision data, primarily adhering to the ISO 3166-2 standard. It offers a programmatic way to access geographical subdivisions for various countries. As of version 0.0.10, it is in an early but functional state, likely receiving updates as data changes or expands, rather than on a strict release cadence. Its key differentiator lies in its simplicity and direct access to structured country-state information without complex APIs or extensive feature sets, making it suitable for applications requiring basic geographical data lookups where detailed geographic features are not needed.","status":"active","version":"0.0.10","language":"javascript","source_language":"en","source_url":"https://github.com/lwhiteley/country-states","tags":["javascript","country","states","federal","countries","state","geoip","iso"],"install":[{"cmd":"npm install country-states","lang":"bash","label":"npm"},{"cmd":"yarn add country-states","lang":"bash","label":"yarn"},{"cmd":"pnpm add country-states","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { compile } = require('country-states');","symbol":"compile","correct":"import { compile } from 'country-states';"},{"note":"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`.","wrong":"const { states } = require('country-states');","symbol":"states","correct":"import { states } from 'country-states';"},{"note":"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.","wrong":"import countryStates from 'country-states';","symbol":"default import","correct":"import * as countryStates from 'country-states';"}],"quickstart":{"code":"import { compile, states } from 'country-states';\n\n// It's crucial to call `compile` with the country codes you intend to use\n// before attempting to retrieve states. This initializes the data for those countries.\n// ISO 3166-1 alpha-2 codes are used here.\ncompile(['US', 'CA', 'DE', 'AU']);\n\nconsole.log('States for United States (US):');\nconst usStates = states('US');\nif (usStates && usStates.length > 0) {\n  console.log(`  Total US states/territories: ${usStates.length}`);\n  console.log('  First 3 US states:', usStates.slice(0, 3).map(s => s.name).join(', '));\n} else {\n  console.log('  No data found for US.');\n}\n\nconsole.log('\\nStates for Germany (DE):');\nconst deStates = states('DE');\nif (deStates && deStates.length > 0) {\n  console.log(`  Total German states/territories: ${deStates.length}`);\n  console.log('  First 3 German states:', deStates.slice(0, 3).map(s => s.name).join(', '));\n} else {\n  console.log('  No data found for DE. Did you include it in compile()?');\n}\n\n// Attempting to access a country not compiled will return undefined or an empty array.\nconsole.log('\\nStates for France (FR) without prior compilation:');\nconst frStates = states('FR');\nif (frStates && frStates.length > 0) {\n  console.log(`  Total FR states/territories: ${frStates.length}`);\n} else {\n  console.log('  No data found for FR, as it was not included in compile().');\n}\n\n// You can inspect the structure of a state object\nif (usStates && usStates.length > 0) {\n  console.log('\\nExample state object (from US):', usStates[0]);\n}","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure `compile(['US', 'DE', ...])` is executed once at application startup or before any `states()` calls for relevant countries.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Pin exact versions (e.g., `\"country-states\": \"0.0.10\"`) in `package.json` and manually test upgrades before deployment.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"For critical applications, cross-reference data with official ISO sources or governmental APIs to ensure accuracy and up-to-dateness.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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`.","cause":"Incorrect import or require statement, or trying to access `states` before the module is properly loaded.","error":"TypeError: states is not a function"},{"fix":"Before calling `states('XX')`, ensure you have executed `compile(['XX', ...])` with 'XX' explicitly listed in the array of country codes.","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.","error":"console.log(states('XX')) returns undefined or an empty array"},{"fix":"Run `npm install country-states` or `yarn add country-states` in your project directory.","cause":"The package has not been installed or is not correctly resolved in your project's `node_modules`.","error":"Cannot find module 'country-states'"}],"ecosystem":"npm"}