### Install via Bun
Source: https://github.com/annexare/countries/blob/main/_autodocs/integration-guide.md
Install the countries-list package using Bun.
```bash
bun add countries-list
```
--------------------------------
### Install countries-list via NPM
Source: https://github.com/annexare/countries/wiki/Installation-&-Usage
Install the package using npm.
```bash
npm install countries-list
```
--------------------------------
### Install countries-list via Bower
Source: https://github.com/annexare/countries/wiki/Installation-&-Usage
Install the package using Bower.
```bash
bower install countries
```
--------------------------------
### Install countries-list via Composer
Source: https://github.com/annexare/countries/wiki/Installation-&-Usage
Install the package using Composer for PHP projects.
```bash
composer require annexare/countries-list
```
--------------------------------
### Install countries-list Package
Source: https://github.com/annexare/countries/blob/main/_autodocs/README.md
Install the countries-list package using npm. This command is typically run once at the beginning of a project.
```bash
npm install countries-list
```
--------------------------------
### IIFE Example: Simple HTML Page
Source: https://github.com/annexare/countries/blob/main/_autodocs/distribution-formats.md
A complete HTML page example demonstrating the IIFE format. It loads the library via a script tag and populates a div with country flags and names.
```html
Countries List Demo
```
--------------------------------
### Complete Currency Entry Example
Source: https://github.com/annexare/countries/blob/main/_autodocs/data-specifications.md
Examples of currency entries, including standard and withdrawn currencies.
```json
{
"UAH": {
"name": "Ukrainian Hryvnia",
"native": "українська гривня",
"symbol": "₴",
"symbolNative": "₴",
"numeric": "980",
"decimals": 2
},
"ANG": {
"name": "Netherlands Antillean Guilder",
"native": "Nederlands-Antilliaanse gulden",
"symbol": "ANG",
"symbolNative": "NAf.",
"numeric": "532",
"decimals": 2,
"withdrawn": true
}
}
```
--------------------------------
### Complete Language Entry Example
Source: https://github.com/annexare/countries/blob/main/_autodocs/data-specifications.md
An example of a complete language entry, including right-to-left indicator.
```json
{
"uk": {
"name": "Ukrainian",
"native": "Українська"
},
"ar": {
"name": "Arabic",
"native": "العربية",
"rtl": 1
}
}
```
--------------------------------
### Complete Country Entry Example
Source: https://github.com/annexare/countries/blob/main/_autodocs/data-specifications.md
An example of a complete country entry in the data format.
```json
{
"UA": {
"name": "Ukraine",
"native": "Україна",
"phone": [380],
"continent": "EU",
"capital": "Kyiv",
"languages": ["uk"]
}
}
```
--------------------------------
### Importing from Main Package
Source: https://github.com/annexare/countries/blob/main/_autodocs/module-structure.md
Examples of how to import all exports or specific types from the main 'countries-list' package.
```typescript
// All imports from the main package
import {
continents,
countries,
languages,
getCountryCode,
getCountryData,
getCountryDataList,
getEmojiFlag,
} from 'countries-list'
// Type imports
import type {
ICountry,
ICountryData,
ILanguage,
TContinentCode,
TCountryCode,
TLanguageCode,
} from 'countries-list'
```
--------------------------------
### CommonJS (CJS) Usage
Source: https://github.com/annexare/countries/blob/main/_autodocs/module-structure.md
Example of how to import from the CommonJS build of the 'countries-list' package.
```javascript
const { countries, getCountryCode } = require('countries-list')
```
--------------------------------
### Language Data Structure Example
Source: https://github.com/annexare/countries/blob/main/README.md
Provides an example of the 'languages' object structure, mapping language codes to their English and native names, and indicating right-to-left text direction.
```typescript
const languages = {
// ...
uk: {
name: 'Ukrainian',
native: 'Українська',
},
ur: {
name: 'Urdu',
native: 'اردو',
rtl: 1,
},
// ...
}
```
--------------------------------
### TypeScript Usage
Source: https://github.com/annexare/countries/blob/main/_autodocs/distribution-formats.md
Example of using the library in a TypeScript project. It shows how to import types and functions, benefiting from static typing and IntelliSense.
```typescript
import { countries, getCountryCode } from 'countries-list'
import type { TCountryCode, ICountryData } from 'countries-list'
// Types are automatically included when importing
const code: TCountryCode = 'UA'
const data = getCountryData(code) // ICountryData
```
--------------------------------
### Importing from Currencies Subpath
Source: https://github.com/annexare/countries/blob/main/_autodocs/module-structure.md
Examples of importing currency utilities and types from the 'countries-list/currencies' subpath.
```typescript
// Import currencies and utilities
import { currencies, getCurrency, getCurrencyByNumeric } from 'countries-list/currencies'
// Type imports
import type { ICurrency, ICurrencyData, TCurrencyCode } from 'countries-list'
```
--------------------------------
### Direct Data Access Example
Source: https://github.com/annexare/countries/blob/main/_autodocs/README.md
Access country and currency data directly using their codes for O(1) lookup.
```typescript
const ukraine = countries['UA'] // O(1) lookup
const uah = currencies['UAH'] // O(1) lookup
```
--------------------------------
### Example Data Organization Flow
Source: https://github.com/annexare/countries/blob/main/_autodocs/data-specifications.md
Illustrates the flow from a data file to a strongly typed API using type definitions and utility functions. This structure promotes self-documentation.
```typescript
// Data File: countries.ts
const countries = { UA: { name: 'Ukraine', ... }, ... }
// Type Definition: types.ts
interface ICountry { name: string; ... }
type TCountryCode = keyof typeof countries
// Exported: index.ts
export { countries } from './data/countries.ts'
// Utility Function: getCountryData.ts
const getCountryData = (iso2: TCountryCode): ICountryData => (...)
// Result: Strongly Typed, Self-Documenting API
```
--------------------------------
### ECMAScript Module (ESM) Usage
Source: https://github.com/annexare/countries/blob/main/_autodocs/module-structure.md
Example of how to import from the ECMAScript Module (ESM) build of the 'countries-list' package.
```javascript
import { countries, getCountryCode } from 'countries-list'
```
--------------------------------
### Using ICurrency Interface
Source: https://github.com/annexare/countries/blob/main/_autodocs/types.md
Demonstrates how to use the ICurrency interface to access currency details such as name, symbol, and decimal places. Includes examples of formatting amounts and checking if a currency has been withdrawn.
```typescript
import type { ICurrency } from 'countries-list'
import { currencies } from 'countries-list/currencies'
const usd: ICurrency = currencies.USD
// {
// name: 'US Dollar',
// native: 'US Dollar',
// symbol: '$',
// symbolNative: '$',
// numeric: '840',
// decimals: 2
// }
// Format amounts
const amount = 100
const formatted = `${usd.symbol}${amount.toFixed(usd.decimals)}` // '$100.00'
// Check if withdrawn
if (!usd.withdrawn) {
// Current currency, safe to use in transactions
}
```
--------------------------------
### Utility Functions
Source: https://github.com/annexare/countries/blob/main/_autodocs/README.md
Reference for all exported utility functions, including their signatures, parameter descriptions, return types, and usage examples.
```APIDOC
## Utility Functions
### `getCountryCode(countryName)`
**Description**: Look up country code by English or native name.
### `getCountryData(iso2)`
**Description**: Get complete country information using the ISO 3166-1 alpha-2 code.
### `getCountryDataList()`
**Description**: Get an array of all countries.
### `getEmojiFlag(countryCode)`
**Description**: Convert a country code to its corresponding emoji flag.
### `getCurrency(code)`
**Description**: Get currency information by its ISO 4217 currency code.
### `getCurrencyByNumeric(numeric)`
**Description**: Get currency information by its ISO 4217 numeric code.
```
--------------------------------
### getCurrency()
Source: https://github.com/annexare/countries/blob/main/_autodocs/GENERATION_REPORT.txt
Retrieves currency information. This function is fully documented with its signature and usage examples.
```APIDOC
## getCurrency()
### Description
Retrieves currency information.
### Method
N/A (Function call)
### Parameters
(Details on parameters are available in the full documentation, including type specifications and descriptions.)
### Response
(Details on return values are available in the full documentation, including type specifications.)
### Request Example
(Usage examples are abundant and cover real-world patterns, including TypeScript integration.)
### Response Example
(Usage examples are abundant and cover real-world patterns, including TypeScript integration.)
```
--------------------------------
### API Reference: Get Currency Data by Code
Source: https://github.com/annexare/countries/blob/main/_autodocs/GENERATION_REPORT.txt
Retrieves detailed information about a currency using its ISO 4217 code.
```typescript
getCurrency(code: TCurrencyCode): ICurrencyData
```
--------------------------------
### Currency Data Structure Example
Source: https://github.com/annexare/countries/blob/main/README.md
Illustrates the detailed structure of the 'currencies' object, including English name, native name, symbol, numeric code, and decimal places for each currency.
```typescript
const currencies = {
// ...
UAH: {
name: 'Ukrainian Hryvnia',
native: 'українська гривня',
symbol: '₴',
symbolNative: '₴',
numeric: '980',
decimals: 2,
},
// ...
}
```
--------------------------------
### Data Example for countries-list
Source: https://github.com/annexare/countries/wiki/Installation-&-Usage
This JSON structure represents the data provided by the countries-list package, including continents, countries, and languages.
```json
{
"continents": {
"AF": "Africa",
"AN": "Antarctica",
"AS": "Asia",
"EU": "Europe",
"NA": "North America",
"OC": "Oceania",
"SA": "South America"
},
"countries": {
"AE": {
"name": "United Arab Emirates",
"native": "دولة الإمارات العربية المتحدة",
"phone": "971",
"continent": "AS",
"capital": "Abu Dhabi",
"currency": "AED",
"languages": [
"ar"
],
"emoji": "🇦🇪",
"emojiU": "U+1F1E6 U+1F1EA"
},
...
"UA": {
"name": "Ukraine",
"native": "Україна",
"phone": "380",
"continent": "EU",
"capital": "Kyiv",
"currency": "UAH",
"languages": [
"uk"
],
"emoji": "🇺🇦",
"emojiU": "U+1F1FA U+1F1E6"
}
},
"languages": {
"ar": {
"name": "Arabic",
"native": "العربية",
"rtl": 1
},
...
"uk": {
"name": "Ukrainian",
"native": "Українська"
}
}
}
```
--------------------------------
### Continent Data Structure Example
Source: https://github.com/annexare/countries/blob/main/README.md
Illustrates the structure of the 'continents' object, mapping continent codes to their English names.
```typescript
const continents = {
AF: 'Africa',
AN: 'Antarctica',
AS: 'Asia',
EU: 'Europe',
NA: 'North America',
OC: 'Oceania',
SA: 'South America',
}
```
--------------------------------
### Country Data Structure Example
Source: https://github.com/annexare/countries/blob/main/README.md
Shows a sample entry from the 'countries' object, detailing the properties available for each country, such as name, native name, phone code, continent, capital, currency, and languages.
```typescript
const countries = {
// ...
UA: {
name: 'Ukraine',
native: 'Україна',
phone: [380],
continent: 'EU',
capital: 'Kyiv',
currency: ['UAH'],
languages: ['uk'],
},
// ...
}
```
--------------------------------
### Accessing Single Currency Data
Source: https://github.com/annexare/countries/blob/main/_autodocs/api-reference-data.md
Demonstrates how to access specific currency objects by their ISO 4217 code from the imported `currencies` object. Includes examples for standard and withdrawn currencies.
```typescript
import { currencies } from 'countries-list/currencies'
// Access single currency
const uah = currencies.UAH
// Returns:
// {
// name: 'Ukrainian Hryvnia',
// native: 'українська гривня',
// symbol: '₴',
// symbolNative: '₴',
// numeric: '980',
// decimals: 2
// }
const usd = currencies.USD
// Returns:
// {
// name: 'US Dollar',
// native: 'US Dollar',
// symbol: '$',
// symbolNative: '$',
// numeric: '840',
// decimals: 2
// }
const jpy = currencies.JPY
// Returns:
// {
// name: 'Japanese Yen',
// native: '日本円',
// symbol: '¥',
// symbolNative: '¥',
// numeric: '392',
// decimals: 0
// }
// Withdrawn currency (still in dataset)
const ang = currencies.ANG
// Returns:
// {
// name: 'Netherlands Antillean Guilder',
// native: 'Nederlands-Antilliaanse gulden',
// symbol: 'ANG',
// symbolNative: 'NAf.',
// numeric: '532',
// decimals: 2,
// withdrawn: true
// }
```
--------------------------------
### Using ICountryData Interface
Source: https://github.com/annexare/countries/blob/main/_autodocs/types.md
Illustrates how to use the ICountryData interface, which extends ICountry, to access both ISO 3166-1 alpha-2 and alpha-3 codes. Shows an example of building a map of ISO codes.
```typescript
import type { ICountryData } from 'countries-list'
import { getCountryData } from 'countries-list'
const countryData: ICountryData = getCountryData('UA')
// {
// iso2: 'UA',
// iso3: 'UKR',
// name: 'Ukraine',
// native: 'Україна',
// capital: 'Kyiv',
// continent: 'EU',
// currency: ['UAH'],
// languages: ['uk'],
// phone: [380]
// }
// Use both codes
console.log(`${countryData.iso2} = ${countryData.iso3}`) // 'UA = UKR'
// Map building
const iso2to3: Record = {}
getCountryDataList().forEach(country => {
iso2to3[country.iso2] = country.iso3
})
```
--------------------------------
### IIFE Usage in HTML
Source: https://github.com/annexare/countries/blob/main/_autodocs/module-structure.md
Example of how to use the Immediately Invoked Function Expression (IIFE) build of the 'countries-list' package within an HTML script tag.
```html
```
--------------------------------
### Getting Country Code by Name
Source: https://github.com/annexare/countries/blob/main/README.md
Demonstrates how to retrieve the ISO 3166-1 alpha-2 country code using either the English or native name of the country.
```typescript
getCountryCode('Ukraine') // 'UA'
getCountryCode('Україна') // 'UA'
```
--------------------------------
### Country Data Structure Example
Source: https://github.com/annexare/countries/wiki/Draft:-v3
Illustrates the main Country object structure, including the 'native' sub-tree for localized names and capitals. This structure is intended for representing country information.
```json
{
"name": "",
"capital": "",
"native": {
"name": "",
"capital": ""
}
}
```
--------------------------------
### API Reference: Get Currency Data by Numeric Code
Source: https://github.com/annexare/countries/blob/main/_autodocs/GENERATION_REPORT.txt
Fetches currency data using its ISO 4217 numeric code. Returns undefined if no currency matches.
```typescript
getCurrencyByNumeric(numeric: string | number): ICurrencyData | undefined
```
--------------------------------
### Basic Country Data Retrieval
Source: https://github.com/annexare/countries/blob/main/_autodocs/README.md
Import and use core functions to get country code, data, and emoji flag. Ensure the 'countries-list' package is installed and imported correctly.
```typescript
import { getCountryCode, getCountryData, getEmojiFlag } from 'countries-list'
const code = getCountryCode('Ukraine') // 'UA'
const data = getCountryData(code) // ICountryData
const flag = getEmojiFlag(code) // '🇺🇦'
console.log(flag, data.name) // '🇺🇦 Ukraine'
```
--------------------------------
### Accessing Country Properties
Source: https://github.com/annexare/countries/blob/main/_autodocs/types.md
Demonstrates how to import and access properties of an ICountry object, such as capital, continent, currency, and languages. Includes examples of type-safe iteration over currency and language codes.
```typescript
import type { ICountry } from 'countries-list'
import { countries } from 'countries-list'
const country: ICountry = countries.UA
// Access properties
const capital = country.capital // 'Kyiv'
const isEuropean = country.continent === 'EU' // true
const acceptedCurrencies = country.currency // ['UAH']
const spokenLanguages = country.languages // ['uk']
// Type-safe iteration
for (const currencyCode of country.currency) {
// currencyCode is guaranteed to be TCurrencyCode
}
for (const languageCode of country.languages) {
// languageCode is guaranteed to be TLanguageCode
}
```
--------------------------------
### Build with esbuild
Source: https://github.com/annexare/countries/blob/main/_autodocs/distribution-formats.md
Use esbuild to bundle your entry points. Specify external dependencies if needed.
```javascript
const result = await esbuild.build({
entryPoints: ['main.ts'],
bundle: true,
external: ['countries-list'], // If external
})
```
--------------------------------
### Get Currency Data
Source: https://github.com/annexare/countries/blob/main/_autodocs/types.md
Demonstrates how to retrieve currency data using the getCurrency function. Useful for accessing specific currency details like code, name, symbol, and decimals.
```typescript
import type { ICurrencyData } from 'countries-list'
import { getCurrency } from 'countries-list/currencies'
const currencyData: ICurrencyData = getCurrency('UAH')
// {
// code: 'UAH',
// name: 'Ukrainian Hryvnia',
// native: 'українська гривня',
// symbol: '₴',
// symbolNative: '₴',
// numeric: '980',
// decimals: 2
// }
// Building maps
const currencyMap: Record = {}
// ... populate with getCurrency calls ...
```
--------------------------------
### Get List of All Countries with Data
Source: https://github.com/annexare/countries/blob/main/_autodocs/api-reference-functions.md
Fetches an array containing complete data for every country in the dataset. Each element includes ISO alpha-2 and alpha-3 codes, names, capitals, and more. Useful for populating dropdowns, performing bulk lookups, or analyzing the entire dataset.
```typescript
import { getCountryDataList } from 'countries-list'
const allCountries = getCountryDataList()
// Returns an array of all countries, e.g.:
// [
// { iso2: 'AC', iso3: 'ASC', name: 'Ascension Island', ... },
// { iso2: 'AD', iso3: 'AND', name: 'Andorra', ... },
// { iso2: 'UA', iso3: 'UKR', name: 'Ukraine', ... },
// ...
// ]
// Find Ukraine in the list
const ukraine = allCountries.find(c => c.iso2 === 'UA')
// Get all countries in Europe
const europeanCountries = allCountries.filter(c => c.continent === 'EU')
// Map country codes to names
const nameMap = allCountries.reduce((map, country) => {
map[country.iso2] = country.name
return map
}, {} as Record)
```
--------------------------------
### Build Project
Source: https://github.com/annexare/countries/blob/main/CLAUDE.md
Use this command to build all workspace packages in the project.
```bash
bun run build
```
--------------------------------
### Format Project with Biome
Source: https://github.com/annexare/countries/blob/main/CLAUDE.md
Runs biome format with the --write flag to automatically format code.
```bash
bun run format
```
--------------------------------
### Build and Test Generated Files
Source: https://github.com/annexare/countries/blob/main/README.md
Use these commands to build and test the generated files within the repository. Ensure you are in the correct directory.
```bash
bun run build
bun run test
```
--------------------------------
### Build Script for Countries List Package
Source: https://github.com/annexare/countries/blob/main/_autodocs/module-structure.md
The package uses 'tsup' for building. Run 'bun run build' to compile all formats, generating minified JSON, JavaScript, and TypeScript declaration files in the 'dist/' directory.
```bash
# Build all formats
bun run build
# Command in packages/countries/package.json
"build": "tsup"
```
--------------------------------
### Get Emoji Flags
Source: https://github.com/annexare/countries/blob/main/_autodocs/integration-guide.md
Generate the corresponding emoji flag for a given country code.
```typescript
import { getEmojiFlag } from 'countries-list'
const flag1 = getEmojiFlag('UA') // '🇺🇦'
const flag2 = getEmojiFlag('US') // '🇺🇸'
const flag3 = getEmojiFlag('FR') // '🇫🇷'
// Use in UI
const countryDisplay = `${getEmojiFlag('UA')} Ukraine` // '🇺🇦 Ukraine'
```
--------------------------------
### getCountryDataList()
Source: https://github.com/annexare/countries/blob/main/_autodocs/GENERATION_REPORT.txt
Retrieves a list of country data. This function is fully documented with its signature and usage examples.
```APIDOC
## getCountryDataList()
### Description
Retrieves a list of country data.
### Method
N/A (Function call)
### Parameters
(Details on parameters are available in the full documentation, including type specifications and descriptions.)
### Response
(Details on return values are available in the full documentation, including type specifications.)
### Request Example
(Usage examples are abundant and cover real-world patterns, including TypeScript integration.)
### Response Example
(Usage examples are abundant and cover real-world patterns, including TypeScript integration.)
```
--------------------------------
### Run a Single Test File
Source: https://github.com/annexare/countries/blob/main/AGENTS.md
Navigates to the test-js package and runs a specific test file using the Bun test runner.
```shell
cd packages/test-js && bun test
```
--------------------------------
### API Reference: Get All Country Data
Source: https://github.com/annexare/countries/blob/main/_autodocs/GENERATION_REPORT.txt
Retrieves a list of all available country data objects.
```typescript
getCountryDataList(): ICountryData[]
```
--------------------------------
### TypeScript Configuration
Source: https://github.com/annexare/countries/blob/main/_autodocs/distribution-formats.md
A sample tsconfig.json configuration that enables module resolution and declaration file generation, ensuring proper type checking and IntelliSense.
```json
{
"compilerOptions": {
"moduleResolution": "node",
"skipLibCheck": true,
"declaration": true
}
}
```
--------------------------------
### Get List of All Countries
Source: https://github.com/annexare/countries/blob/main/_autodocs/GENERATION_REPORT.txt
Retrieves a list of all available countries. This function provides a comprehensive dataset for all countries.
```typescript
import { getCountryDataList } from 'countries-list';
const countries = getCountryDataList();
console.log(countries.length); // 249
console.log(countries[0].name); // "Afghanistan"
```
--------------------------------
### API Reference: Get Emoji Flag
Source: https://github.com/annexare/countries/blob/main/_autodocs/GENERATION_REPORT.txt
Generates the emoji flag representation for a given country code.
```typescript
getEmojiFlag(countryCode: TCountryCode): string
```
--------------------------------
### Lint Project with Biome
Source: https://github.com/annexare/countries/blob/main/CLAUDE.md
Runs biome check to ensure code quality and style adherence.
```bash
bun run lint
```
--------------------------------
### Run All Tests
Source: https://github.com/annexare/countries/blob/main/CLAUDE.md
Executes all tests within the project.
```bash
bun run test
```
--------------------------------
### Distribution Format: JSON Data Files
Source: https://github.com/annexare/countries/blob/main/_autodocs/GENERATION_REPORT.txt
JSON files containing the project's data, available in full and minimal formats.
```bash
JSON data files (full and minimal)
```
--------------------------------
### Get Country Information
Source: https://github.com/annexare/countries/blob/main/_autodocs/integration-guide.md
Fetch detailed information about a specific country using its ISO 3166-1 alpha-2 code.
```typescript
import { getCountryData } from 'countries-list'
const ukraine = getCountryData('UA')
console.log(ukraine.name) // 'Ukraine'
console.log(ukraine.iso3) // 'UKR'
console.log(ukraine.capital) // 'Kyiv'
console.log(ukraine.continent) // 'EU'
console.log(ukraine.currency) // ['UAH']
console.log(ukraine.languages) // ['uk']
console.log(ukraine.phone) // [380]
```
--------------------------------
### Main Exports Import
Source: https://github.com/annexare/countries/blob/main/_autodocs/README.md
Import core functions and data from the main entry point of the library.
```typescript
// Main exports
import { countries, getCountryCode } from 'countries-list'
// Type imports
import type { TCountryCode, ICountry } from 'countries-list'
```
--------------------------------
### Run Single Test File
Source: https://github.com/annexare/countries/blob/main/CLAUDE.md
Executes a specific test file using the Bun test runner. Navigate to the test-js package directory first.
```bash
cd packages/test-js && bun test
```
--------------------------------
### Importing Interfaces and Main Data
Source: https://github.com/annexare/countries/blob/main/README.md
Import necessary interfaces and types for strong typing, along with the main data exports for continents, countries, and languages. Also shows how to import utility functions.
```typescript
import type {
ICountry,
ICountryData,
ILanguage,
TContinentCode,
TCountryCode,
TLanguageCode,
} from 'countries-list'
import { continents, countries, languages } from 'countries-list'
import { getCountryCode, getCountryData, getCountryDataList, getEmojiFlag } from 'countries-list'
```
--------------------------------
### ISO 639-1 Language Codes
Source: https://github.com/annexare/countries/blob/main/_autodocs/data-specifications.md
Examples of ISO 639-1 language codes. Used to specify the language of a resource or text.
```text
en = English
uk = Ukrainian
zh = Mandarin Chinese (simplified)
ar = Arabic
```
--------------------------------
### Run Continuous Integration Checks
Source: https://github.com/annexare/countries/blob/main/CLAUDE.md
Performs linting, building, and testing as part of the CI process.
```bash
bun run ci
```
--------------------------------
### ISO 3166-1 Country Codes
Source: https://github.com/annexare/countries/blob/main/_autodocs/data-specifications.md
Examples of ISO 3166-1 alpha-2 and alpha-3 country codes. These are used to identify countries.
```text
UA (Ukraine) = UKR
US (United States) = USA
GB (United Kingdom) = GBR
FR (France) = FRA
```
--------------------------------
### API Reference: Get Country Data
Source: https://github.com/annexare/countries/blob/main/_autodocs/GENERATION_REPORT.txt
Fetches detailed data for a country using its ISO 3166-1 alpha-2 code.
```typescript
getCountryData(iso2: TCountryCode): ICountryData
```
--------------------------------
### Getting Country Data by Code
Source: https://github.com/annexare/countries/blob/main/README.md
Retrieves detailed data for a specific country using its ISO 3166-1 alpha-2 code.
```typescript
getCountryData('UA') // ICountryData
```
--------------------------------
### Lint and Fix Project with Biome
Source: https://github.com/annexare/countries/blob/main/CLAUDE.md
Runs biome check with the --write flag to automatically fix linting issues.
```bash
bun run lint:fix
```
--------------------------------
### getCurrencyByNumeric()
Source: https://github.com/annexare/countries/blob/main/_autodocs/GENERATION_REPORT.txt
Retrieves currency information using its numeric code. This function is fully documented with its signature and usage examples, and returns undefined on no match.
```APIDOC
## getCurrencyByNumeric()
### Description
Retrieves currency information using its numeric code. Returns undefined on no match.
### Method
N/A (Function call)
### Parameters
(Details on parameters are available in the full documentation, including type specifications and descriptions.)
### Response
(Details on return values are available in the full documentation, including type specifications.)
### Request Example
(Usage examples are abundant and cover real-world patterns, including TypeScript integration.)
### Response Example
(Usage examples are abundant and cover real-world patterns, including TypeScript integration.)
```
--------------------------------
### Create GitHub Release
Source: https://github.com/annexare/countries/blob/main/CLAUDE.md
Creates a GitHub release, generates a git tag, and triggers the npm publish workflow.
```bash
gh release create vX.Y.Z
```
--------------------------------
### ISO 4217 Currency Codes
Source: https://github.com/annexare/countries/blob/main/_autodocs/data-specifications.md
Examples of ISO 4217 currency codes, including alpha-3 and numeric representations. Used for financial data.
```text
USD = 840 (US Dollar)
EUR = 978 (Euro)
UAH = 980 (Ukrainian Hryvnia)
JPY = 392 (Japanese Yen)
```
--------------------------------
### Example Minimal Mapping JSON
Source: https://github.com/annexare/countries/blob/main/_autodocs/distribution-formats.md
This JSON structure represents a minimal mapping, such as country codes to their Alpha-3 equivalents. It's highly optimized for size.
```json
{
"AC": "ASC",
"AD": "AND",
"AE": "ARE",
"AF": "AFG",
...
"UA": "UKR",
...
"ZW": "ZWE"
}
```
--------------------------------
### Importing Minimal Currency Maps
Source: https://github.com/annexare/countries/blob/main/README.md
Import minimal JSON maps for currency symbols and numeric codes. These are optimized for quick lookups.
```typescript
import currencySymbols from 'countries-list/minimal/currencies.symbol.min.json'
import currencyNumbers from 'countries-list/minimal/currencies.numeric.min.json'
```
--------------------------------
### Get Currency Information by Country Code
Source: https://github.com/annexare/countries/blob/main/_autodocs/GENERATION_REPORT.txt
Retrieves currency information associated with a specific country code. This function is useful for displaying currency details.
```typescript
import { getCurrency } from 'countries-list';
const currency = getCurrency('GB');
console.log(currency.name); // "Pound Sterling"
console.log(currency.symbol); // "£"
```
--------------------------------
### Importing Minimal Country Code Mappings
Source: https://github.com/annexare/countries/blob/main/_autodocs/api-reference-data.md
Demonstrates importing a minimal JSON file for country code mappings (2-letter to 3-letter ISO codes). This is an efficient alternative for specific lookup needs.
```typescript
import countries2to3 from 'countries-list/minimal/countries.2to3.min.json'
// Lightweight mapping: ISO 3166-1 alpha-2 -> alpha-3
const iso3 = countries2to3['UA'] // 'UKR'
const iso3us = countries2to3['US'] // 'USA'
// These minimal files are zero-overhead alternatives when you only need
// specific mappings without the full data structure
```
--------------------------------
### Use Minimal JSON Data Files
Source: https://github.com/annexare/countries/blob/main/_autodocs/integration-guide.md
For size-critical applications, utilize pre-built minimal JSON files for faster loading and smaller footprint. These files provide essential mappings.
```typescript
// ~2KB for simple mappings
import countries2to3 from 'countries-list/minimal/countries.2to3.min.json'
import countriesEmoji from 'countries-list/minimal/countries.emoji.min.json'
// Lightweight lookup
const iso3 = countries2to3['UA'] // 'UKR'
const flag = countriesEmoji['UA'] // '🇺🇦'
```
--------------------------------
### Get Country Data by Code
Source: https://github.com/annexare/countries/blob/main/_autodocs/GENERATION_REPORT.txt
Retrieves detailed data for a specific country using its alpha-2 or alpha-3 code. Ensure the country code is valid.
```typescript
import { getCountryData } from 'countries-list';
const country = getCountryData('US');
console.log(country.name); // "United States"
```
--------------------------------
### getEmojiFlag()
Source: https://github.com/annexare/countries/blob/main/_autodocs/GENERATION_REPORT.txt
Retrieves the emoji flag for a given country. This function is fully documented with its signature and usage examples, and handles invalid input by returning an empty string.
```APIDOC
## getEmojiFlag()
### Description
Retrieves the emoji flag for a given country. Returns an empty string on invalid input.
### Method
N/A (Function call)
### Parameters
(Details on parameters are available in the full documentation, including type specifications and descriptions.)
### Response
(Details on return values are available in the full documentation, including type specifications.)
### Request Example
(Usage examples are abundant and cover real-world patterns, including TypeScript integration.)
### Response Example
(Usage examples are abundant and cover real-world patterns, including TypeScript integration.)
```
--------------------------------
### API Reference: Get Country Code
Source: https://github.com/annexare/countries/blob/main/_autodocs/GENERATION_REPORT.txt
Retrieves the ISO 3166-1 alpha-2 country code for a given country name. Returns false if the country is not found.
```typescript
getCountryCode(countryName: string): TCountryCode | false
```
--------------------------------
### Get Currency Information by Numeric Code
Source: https://github.com/annexare/countries/blob/main/_autodocs/GENERATION_REPORT.txt
Retrieves currency information using its numeric ISO 4217 code. Returns undefined if no currency matches the numeric code.
```typescript
import { getCurrencyByNumeric } from 'countries-list';
const currency = getCurrencyByNumeric(840); // Numeric code for USD
console.log(currency.name); // "United States Dollar"
console.log(currency.code); // "USD"
```
--------------------------------
### Using ILanguage Interface
Source: https://github.com/annexare/countries/blob/main/_autodocs/types.md
Shows how to import and use the ILanguage interface to access language details like name, native name, and right-to-left text direction. Includes filtering for RTL languages.
```typescript
import type { ILanguage } from 'countries-list'
import { languages } from 'countries-list'
const english: ILanguage = languages.en
// { name: 'English', native: 'English' }
const arabic: ILanguage = languages.ar
// { name: 'Arabic', native: 'العربية', rtl: 1 }
// Determine text direction
const direction = arabic.rtl ? 'rtl' : 'ltr'
// Filter RTL languages
const rtlLanguages = Object.values(languages).filter(lang => lang.rtl)
```
--------------------------------
### Refresh Currencies Dataset
Source: https://github.com/annexare/countries/blob/main/README.md
Refresh the currencies dataset by navigating to the scripts directory and running the currency generation command. This requires an internet connection.
```bash
cd packages/scripts && bun run generate:currencies
```
--------------------------------
### Use ES Module in Browser
Source: https://github.com/annexare/countries/blob/main/_autodocs/integration-guide.md
Integrate the library in browsers using ES Modules for modern JavaScript environments. This is the recommended approach for web applications.
```html
```
--------------------------------
### Accessing Country Data
Source: https://github.com/annexare/countries/blob/main/_autodocs/api-reference-data.md
Shows how to retrieve individual country data objects by their ISO 3166-1 alpha-2 codes, including details for transcontinental and dependent territories. Also demonstrates iterating over all countries and filtering by continent or currency.
```typescript
import { countries } from 'countries-list'
// Access single country
const ukraine = countries.UA
// Returns:
// {
// name: 'Ukraine',
// native: 'Україна',
// capital: 'Kyiv',
// continent: 'EU',
// currency: ['UAH'],
// languages: ['uk'],
// phone: [380]
// }
const us = countries.US
// Returns:
// {
// name: 'United States',
// native: 'United States',
// capital: 'Washington, D.C.',
// continent: 'NA',
// currency: ['USD'],
// languages: ['en'],
// phone: [1]
// }
// Transcontinental country
const ru = countries.RU
// Returns:
// {
// ...
// continent: 'EU',
// continents: ['EU', 'AS'],
// ...
// }
// Dependent territory
const ax = countries.AX
// Returns:
// {
// name: 'Åland Islands',
// ...
// partOf: 'FI', // Finland
// ...
// }
// Iterate over all countries
for (const [code, country] of Object.entries(countries)) {
console.log(`${code}: ${country.name}`)
}
// Find all countries in Europe
const europeanCountries = Object.entries(countries)
.filter(([_, country]) => country.continent === 'EU')
.map(([code, _]) => code)
// Find all countries using a specific currency
const dollarCountries = Object.entries(countries)
.filter(([_, country]) => country.currency.includes('USD'))
.map(([code, _]) => code)
```
--------------------------------
### Accessing Language Data
Source: https://github.com/annexare/countries/blob/main/_autodocs/api-reference-data.md
Illustrates how to retrieve language data objects by ISO 639-1 codes, including native names and RTL directionality. Also shows how to check for RTL languages and iterate over all available languages.
```typescript
import { languages } from 'countries-list'
// Access single language
const ukrainian = languages.uk
// Returns:
// {
// name: 'Ukrainian',
// native: 'Українська'
// }
const arabic = languages.ar
// Returns:
// {
// name: 'Arabic',
// native: 'العربية',
// rtl: 1
// }
const english = languages.en
// Returns:
// {
// name: 'English',
// native: 'English'
// }
// Check if language is RTL
if (languages.ar.rtl) {
console.log('Arabic is right-to-left')
}
// Find all RTL languages
const rtlLanguages = Object.entries(languages)
.filter(([_, lang]) => lang.rtl)
.map(([code, lang]) => ({ code, name: lang.name }))
// Iterate over all languages
for (const [code, lang] of Object.entries(languages)) {
console.log(`${code}: ${lang.name} (${lang.native})`)
}
```
--------------------------------
### Get Currency by Numeric Code
Source: https://github.com/annexare/countries/blob/main/_autodocs/integration-guide.md
Fetches currency details using its numeric code. Returns undefined if no match is found. Safe chaining can be used to provide default values.
```typescript
import { getCurrencyByNumeric } from 'countries-list/currencies'
// Returns undefined on no match
const currency = getCurrencyByNumeric('999')
if (currency) {
console.log(currency.name)
} else {
console.log('Currency not found')
}
// Safe chaining
const symbol = getCurrencyByNumeric('840')?.symbol ?? '?'
```
--------------------------------
### Currencies (Optional Import)
Source: https://github.com/annexare/countries/blob/main/_autodocs/README.md
Reference for currency-specific functions available via an optional import.
```APIDOC
## Currencies (Optional Import)
### `getCurrency(code)`
**Description**: Get currency information by its ISO 4217 currency code.
### `getCurrencyByNumeric(numeric)`
**Description**: Get currency information by its ISO 4217 numeric code.
```
--------------------------------
### Get Emoji Flag for Country Code
Source: https://github.com/annexare/countries/blob/main/_autodocs/api-reference-functions.md
Converts a 2-letter country code into its corresponding Unicode emoji flag sequence. Invalid or non-conforming codes return an empty string.
```typescript
import { getEmojiFlag } from 'countries-list'
// Valid country codes
const flag1 = getEmojiFlag('UA') // Returns '🇺🇦'
const flag2 = getEmojiFlag('US') // Returns '🇺🇸'
const flag3 = getEmojiFlag('GB') // Returns '🇬🇧'
const flag4 = getEmojiFlag('FR') // Returns '🇫🇷'
const flag5 = getEmojiFlag('JP') // Returns '🇯🇵'
// Invalid codes return empty string
const flag6 = getEmojiFlag('XX') // Returns ''
const flag7 = getEmojiFlag('u') // Returns '' (lowercase not allowed)
```
--------------------------------
### Importing Countries List in Browser (ES Module)
Source: https://github.com/annexare/countries/blob/main/_autodocs/distribution-formats.md
Load the countries-list package in a browser using an ES Module import, specifying the path to the ESM distribution file.
```html
```
--------------------------------
### Distribution Format: TypeScript Definitions
Source: https://github.com/annexare/countries/blob/main/_autodocs/GENERATION_REPORT.txt
TypeScript declaration files for type safety.
```bash
TypeScript Definitions: dist/*.d.ts
```
--------------------------------
### Country Functions
Source: https://github.com/annexare/countries/blob/main/_autodocs/GENERATION_REPORT.txt
This section details the functions available for retrieving country-related information. Each function includes its type signature, parameter details, return type, behavior description, and usage examples.
```APIDOC
## Function Reference
This document details the functions available for retrieving country-related information. Each function includes its type signature, parameter details, return type, behavior description, and usage examples.
### `getCountryCode(countryName: string): TCountryCode | false`
**Description**: Retrieves the country code for a given country name.
**Parameters**:
- `countryName` (string) - The name of the country.
**Returns**:
- `TCountryCode | false` - The country code if found, otherwise false.
### `getCountryData(iso2: TCountryCode): ICountryData`
**Description**: Retrieves detailed data for a country using its ISO 3166-1 alpha-2 code.
**Parameters**:
- `iso2` (TCountryCode) - The ISO 3166-1 alpha-2 code of the country.
**Returns**:
- `ICountryData` - An object containing the country's data.
### `getCountryDataList(): ICountryData[]`
**Description**: Retrieves a list of all available country data objects.
**Returns**:
- `ICountryData[]` - An array of country data objects.
### `getEmojiFlag(countryCode: TCountryCode): string`
**Description**: Generates the emoji flag for a given country code.
**Parameters**:
- `countryCode` (TCountryCode) - The country code.
**Returns**:
- `string` - The emoji flag string.
### `getCurrency(code: TCurrencyCode): ICurrencyData`
**Description**: Retrieves detailed data for a currency using its ISO 4217 code.
**Parameters**:
- `code` (TCurrencyCode) - The ISO 4217 code of the currency.
**Returns**:
- `ICurrencyData` - An object containing the currency's data.
### `getCurrencyByNumeric(numeric: string | number): ICurrencyData | undefined`
**Description**: Retrieves currency data using its numeric code.
**Parameters**:
- `numeric` (string | number) - The numeric code of the currency.
**Returns**:
- `ICurrencyData | undefined` - An object containing the currency's data, or undefined if not found.
```
--------------------------------
### Importing Currency Data and Utilities
Source: https://github.com/annexare/countries/blob/main/README.md
Import currency-specific types, data, and utility functions from the 'countries-list/currencies' subpath. This allows for efficient handling of currency information without bloating the main bundle.
```typescript
import type { ICurrency, ICurrencyData, TCurrencyCode } from 'countries-list'
import { currencies, getCurrency, getCurrencyByNumeric } from 'countries-list/currencies'
```
--------------------------------
### Distribution Format: IIFE
Source: https://github.com/annexare/countries/blob/main/_autodocs/GENERATION_REPORT.txt
Immediately Invoked Function Expression format for browser environments.
```bash
IIFE: dist/index.iife.js
```