ts-react-emoji-flag

Display country flags using Unicode emoji - no images or SVGs required, works even on Windows!

Overview

The most efficient way to display country flags in React applications - using Unicode emoji characters directly. Supports all modern browsers and operating systems.

Example: "🇨🇭" (If this looks like a Swiss flag, your system supports emoji flags natively)

Installation

npm install ts-react-emoji-flag
# or
yarn add ts-react-emoji-flag

Usage

Basic Component Usage

import CountryFlag from 'ts-react-emoji-flag';

function MyComponent() {
  return <CountryFlag countryCode="US" title="United States" />;
}

Alternative Usage with Hook and Function

import { useCountryFlag, flag } from 'ts-react-emoji-flag';

function MyComponent() {
  // Initialize the flag support
  useCountryFlag({ className: "country-flag" });

  return (
    <div className="country-flag">
      {flag("JP")} Japan
    </div>
  );
}

API Reference

CountryFlag Component

<CountryFlag 
  countryCode="FR"       // Required: ISO 3166-1 alpha-2 country code
  title="France"         // Optional: Text for the title attribute
  className="my-flag"    // Optional: Additional CSS class
  forceLoadFont={false}  // Optional: Force custom font loading even on systems with native support
/>

useCountryFlag Hook

useCountryFlag({
  className: "country-flag",  // Optional: CSS class name (default: "country-flag")
  forceLoadFont: false        // Optional: Force custom font loading
});

flag Function

flag("DE"); // Returns a JSX element with the German flag emoji

TypeScript Support

This library includes TypeScript definitions. Example usage with TypeScript:

import CountryFlag, { useCountryFlag, flag } from 'ts-react-emoji-flag';

const MyComponent: React.FC = () => {
  return <CountryFlag countryCode="CA" title="Canada" />;
};

Windows Compatibility

On Windows, which doesn't natively display country flags from Unicode, the library automatically loads a special font to ensure proper flag display. You don't need to do anything extra for this feature to work.

If you want to force the custom font loading even on systems with native support, use the forceLoadFont prop:

<CountryFlag countryCode="IT" forceLoadFont={true} />

How It Works

The library:

1. Converts country codes to their corresponding Unicode flag sequence
2. Automatically detects if you're on Windows
3. Loads a special font only when needed for compatibility
4. Applies the appropriate CSS to ensure proper display

Credits

Inspired by country-flag-emoji-polyfill

Fork

This project is a fork of react-country-flag