@iseer/flags

React components for circular and rectangular country flags

A lightweight React component library for displaying country flags in two styles: circular and rectangular. All flags are served from Iseer's CDN for minimal bundle size.

📦 Installation

npm install @iseer/flags

🚀 Usage

Circular Flags

import { CircularFlag } from '@iseer/flags';

function MyComponent() {
  return <CircularFlag countryCode="bd" height="50" />;
}

For example, the following code:

<CircularFlag countryCode="br" height="48" />
<CircularFlag countryCode="cn" height="48" />
<CircularFlag countryCode="gb" height="48" />
<CircularFlag countryCode="id" height="48" />
<CircularFlag countryCode="in" height="48" />
<CircularFlag countryCode="ng" height="48" />
<CircularFlag countryCode="ru" height="48" />
<CircularFlag countryCode="us" height="48" />

...produces this:

Rectangular Flags

import { RectangularFlag } from '@iseer/flags';

function MyComponent() {
  return <RectangularFlag countryCode="us" height="30" />;
}

For example, the following code:

<RectangularFlag countryCode="br" height="32" />
<RectangularFlag countryCode="cn" height="32" />
<RectangularFlag countryCode="gb" height="32" />
<RectangularFlag countryCode="id" height="32" />
<RectangularFlag countryCode="in" height="32" />
<RectangularFlag countryCode="ng" height="32" />
<RectangularFlag countryCode="ru" height="32" />
<RectangularFlag countryCode="us" height="32" />

...produces this:

📋 Props

Both CircularFlag and RectangularFlag accept:

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | countryCode | string | Yes | - | ISO country code (e.g., 'us', 'bd', 'gb') | | height | number \| string | No | 100 | Height of the flag image | | ...rest | ImgHTMLAttributes | No | - | All standard <img> tag attributes |

All standard <img> attributes are supported:

<CircularFlag 
  countryCode="gb" 
  height="40"
  className="shadow-lg"
  style={{ cursor: 'pointer' }}
  onClick={() => console.log('Flag clicked!')}
  alt="United Kingdom Flag"
/>

🌍 Available Flags

• Circular flags: 423 country codes
• Rectangular flags: 262 country codes

Common Country Codes

bd, us, gb, in, cn, jp, de, fr, ca, au, and many more!

Validation

Invalid country codes automatically fallback to 'xx' (unknown flag).

<CircularFlag countryCode="invalid" /> 
// Displays the 'xx' (unknown) flag

🔍 TypeScript Support

Full TypeScript support included:

import { CircularFlag, CircularFlagProps } from '@iseer/flags';

const MyFlag: React.FC = () => {
  return <CircularFlag countryCode="bd" height="50" />;
};

📊 Checking Valid Codes

You can programmatically check if a country code is valid:

import { circularFlags, rectangularFlags } from '@iseer/flags';

console.log(circularFlags['bd']); // true
console.log(circularFlags['xyz']); // undefined

console.log(rectangularFlags['us']); // true

🎨 Example Usage

Flag Selector

import { CircularFlag } from '@iseer/flags';

function FlagSelector() {
  const countries = ['bd', 'us', 'gb', 'in', 'cn'];
  
  return (
    <div style={{ display: 'flex', gap: '10px' }}>
      {countries.map(code => (
        <CircularFlag 
          key={code} 
          countryCode={code} 
          height="40"
          style={{ cursor: 'pointer' }}
        />
      ))}
    </div>
  );
}

User Profile Badge

<div className="user-profile">
  <RectangularFlag countryCode={user.country} height="25" />
  <span>{user.name}</span>
</div>

⚡ Performance

• Tiny bundle size: Only ~2KB (flags loaded from CDN)
• CDN-hosted: Fast delivery via Iseer's global CDN
• Lazy loading: Flags load on-demand
• Browser caching: Automatic caching for repeat loads

📝 License

This project is released under the Apache License 2.0.

🔗 Resources

• CDN Base URL: https://storage.iseer.co/assets/flags/
• Circular Flags: https://storage.iseer.co/assets/flags/circular_flags/{code}.svg
• Rectangular Flags: https://storage.iseer.co/assets/flags/retangular_flags/{code}.svg

Made with ❤️ by Iseer