npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

country-flag-emojis

v1.0.4

Published

A TypeScript library providing country flag emojis with metadata.

Downloads

214

Readme

Country Flag Emojis 🏳️

Features

🚩 Country flag emojis with metadata: Easily access flag emojis along with relevant metadata for each country, enhancing data clarity and presentation.

✅ Type-safe: Ensure code reliability and improve development speed with TypeScript type safety, reducing runtime errors and offering autocompletion.

🪶 Optimized for tree-shaking: Keep your bundle size minimal with tree-shaking, importing only what you need without unnecessary overhead.

📦 No runtime dependencies: This library has no external runtime dependencies, ensuring a lightweight footprint and faster load times in any JavaScript or TypeScript project.

🔗 Easy integration: Compatible with any JavaScript or TypeScript setup, allowing seamless adoption without complex configurations.

Installation

npm install country-flag-emojis

Usage

Recommended: Use the CountryFlag Object for Lookup

Leverage the CountryFlag object to efficiently access country flag data using ISO alpha-2 or alpha-3 codes.

import CountryFlag from "country-flag-emojis";

// Using ISO alpha-2 code
const japanFlagAlpha2 = CountryFlag.byCountryCode("JP");
console.log('Japan Flag (Alpha-2):', japanFlagAlpha2);
// Output:
// Japan Flag (Alpha-2): {
//   flag: "🇯🇵",
//   isoAlpha2: "JP",
//   isoAlpha3: "JPN",
//   unicode: "U+1F1EF,U+1F1F5",
//   nameEnglish: "Japan"
// }

// Using ISO alpha-3 code
const japanFlagAlpha3 = CountryFlag.byCountryCode('JPN');
console.log('Japan Flag (Alpha-3):', japanFlagAlpha3);
// Output:
// Japan Flag (Alpha-3): {
//   flag: "🇯🇵",
//   isoAlpha2: "JP",
//   isoAlpha3: "JPN",
//   unicode: "U+1F1EF,U+1F1F5",
//   nameEnglish: "Japan"
// }

// Retrieving just the emoji flag using ISO alpha-2 code
const japanEmojiAlpha2 = CountryFlag.emojiByCountryCode('JP');
console.log('Japan Emoji (Alpha-2):', japanEmojiAlpha2);
// Output:
// Japan Emoji (Alpha-2): 🇯🇵

// Retrieving just the emoji flag using ISO alpha-3 code
const japanEmojiAlpha3 = CountryFlag.emojiByCountryCode('JPN');
console.log('Japan Emoji (Alpha-3):', japanEmojiAlpha3);
// Output:
// Japan Emoji (Alpha-3): 🇯🇵

Alternative: Named Imports of Individual Flag Emojis

You can also import individual flags directly using named exports from the flags/index.ts. This method is less efficient but useful if you need to import multiple specific flags.

import { DE, JP, ES } from 'country-flag-emojis/lib/flags';

console.log(DE); // 🇩🇪
console.log(JP); // 🇯🇵
console.log(ES); // 🇪🇸

Error Handling

The CountryFlag object methods will throw the following errors:

  • InvalidInputError: If the input is null, undefined, or an empty string.
  • InvalidLengthError: If the country code is either not exactly 2 or 3 characters long.
  • CountryNotFoundError: If the provided country code is not supported.
import CountryFlag from "country-flag-emojis";
import { CountryNotFoundError } from 'country-flag-emojis';

try {
  const flag = CountryFlag.byCountryCode('XYZ');
} catch (error) {
  if (error instanceof CountryNotFoundError) {
    console.error(`Country code not found: ${error.message}`);
  } else {
    console.error(`An unexpected error occurred: ${error}`);
  }
}

Types

The CountryFlag interface defines the structure of the country flag objects:

interface CountryFlag {
    flag: string;        // The emoji flag
    isoAlpha2: string;   // The ISO 3166-1 alpha-2 country code
    isoAlpha3: string;   // The ISO 3166-1 alpha-3 country code
    unicode: string;     // Unicode representation of the emoji
    nameEnglish: string; // English name of the country
}

Building the Library

npm run build

This generates CommonJS and ES Module builds in the dist directory.

Additional Information

Tree-Shakable Exports

The library uses named exports for individual flags in flags/index.ts, enabling effective tree-shaking. This ensures that only the flags you import are included in your final bundle, optimizing performance and reducing bundle size.

Example of Named Exports in flags/index.ts:

export { default as DE } from "./DE";
export { default as JP } from "./JP";
export { default as US } from "./US";
// ... more exports

Type Consistency

All flag files and the mapping file utilize the CountryFlag interface from types.ts to ensure consistent typing across the library.

Example lib/types.ts:

/**
 * Interface representing the structure of each country flag.
 */
export interface CountryFlag {
    flag: string;        // Actual Emoji (e.g., "🇦🇩")
    isoAlpha2: string;   // Country ISO alpha-2 code (e.g., "AD")
    isoAlpha3: string;   // Country ISO alpha-3 code (e.g., "AND")
    unicode: string;     // Unicode code points (e.g., "U+1F1EA,U+1F1FA")
    nameEnglish: string; // English name of the country (e.g., "Andorra")
}

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT License