Country Flag Emoji Library with Metadata – country-flag-emojis

The country-flag-emojis library provides a TypeScript solution for managing country flag emojis and metadata. This library delivers flag emojis with ISO codes, country names, and Unicode data without external dependencies.

The library supports country flag management through ISO alpha-2 and alpha-3 codes. Developers can access flag emojis and corresponding metadata through a straightforward API. The TypeScript implementation includes built-in type safety to prevent runtime errors.

country-flag-emojis maintains a minimal footprint through tree-shaking optimization. This approach reduces bundle size by importing only required flag data. The absence of runtime dependencies further minimizes the package size.

How to use it:

1. Install country-flag-emojis package with NPM.

# NPM
$ npm install country-flag-emojis

2. Import the library into your project:

import CountryFlag from "country-flag-emojis";

3. Use the CountryFlag object and ISO alpha-2 or alpha-3 codes to retrieve country flag data.

const usFlagAlpha2 = CountryFlag.byCountryCode('US');
console.log('US Flag (Alpha-2):', usFlagAlpha2);
// flag: "🇺🇸"
// isoAlpha2: "US"
// isoAlpha3: "USA"
// nameEnglish: "United States"
// unicode: "U+1F1FA,U+1F1F8"

const usFlagAlpha3 = CountryFlag.byCountryCode('USA');
console.log('US Flag (Alpha-3):', usFlagAlpha3);
// flag: "🇺🇸"
// isoAlpha2: "US"
// isoAlpha3: "USA"
// nameEnglish: "United States"
// unicode: "U+1F1FA,U+1F1F8"

4. Retrieve just the emoji flag:

const usEmoji = CountryFlag.emojiByCountryCode("US");
console.log(usEmoji); // 🇺🇸

5. The library provides specific error types for better debugging:

import CountryFlag from "country-flag-emojis";
import { CountryNotFoundError } from 'country-flag-emojis';
try {
  const flag = CountryFlag.byCountryCode('CSS');
} catch (error) {
  if (error instanceof CountryNotFoundError) {
    console.error(`Country code not found: ${error.message}`);
  } else {
    console.error(`An unexpected error occurred: ${error}`);
  }
}

6. Optimize your imports for better tree-shaking:

mport { DE, US, ES } from 'country-flag-emojis/flags';
console.log(DE); // 🇩🇪
console.log(US); // 🇺🇸
console.log(ES); // 🇪🇸