npm package: @iseer/flags
Description: React components for circular and rectangular country flags from Iseer CDN
Author: Iseer
Latest version: 0.1.1

# @iseer/flags

> React components for circular and rectangular country flags

[![NPM](https://img.shields.io/npm/v/@iseer/flags.svg)](https://www.npmjs.com/package/@iseer/flags) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

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

```bash
npm install @iseer/flags
```

## 🚀 Usage

### Circular Flags

```jsx
import { CircularFlag } from '@iseer/flags';

function MyComponent() {
  return <CircularFlag countryCode="bd" height="50" />;
}
```

For example, the following code:

```jsx
<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:

<img src="https://storage.iseer.co/assets/flags/circular_flags/br.svg" width="48"> <img src="https://storage.iseer.co/assets/flags/circular_flags/cn.svg" width="48"> <img src="https://storage.iseer.co/assets/flags/circular_flags/gb.svg" width="48"> <img src="https://storage.iseer.co/assets/flags/circular_flags/id.svg" width="48"> <img src="https://storage.iseer.co/assets/flags/circular_flags/in.svg" width="48"> <img src="https://storage.iseer.co/assets/flags/circular_flags/ng.svg" width="48"> <img src="https://storage.iseer.co/assets/flags/circular_flags/ru.svg" width="48"> <img src="https://storage.iseer.co/assets/flags/circular_flags/us.svg" width="48">

### Rectangular Flags

```jsx
import { RectangularFlag } from '@iseer/flags';

function MyComponent() {
  return <RectangularFlag countryCode="us" height="30" />;
}
```

For example, the following code:

```jsx
<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:

<img src="https://storage.iseer.co/assets/flags/retangular_flags/br.svg" height="32"> <img src="https://storage.iseer.co/assets/flags/retangular_flags/cn.svg" height="32"> <img src="https://storage.iseer.co/assets/flags/retangular_flags/gb.svg" height="32"> <img src="https://storage.iseer.co/assets/flags/retangular_flags/id.svg" height="32"> <img src="https://storage.iseer.co/assets/flags/retangular_flags/in.svg" height="32"> <img src="https://storage.iseer.co/assets/flags/retangular_flags/ng.svg" height="32"> <img src="https://storage.iseer.co/assets/flags/retangular_flags/ru.svg" height="32"> <img src="https://storage.iseer.co/assets/flags/retangular_flags/us.svg" height="32">

## 📋 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:

```jsx
<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).

```jsx
<CircularFlag countryCode="invalid" /> 
// Displays the 'xx' (unknown) flag
```

## 🔍 TypeScript Support

Full TypeScript support included:

```tsx
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:

```jsx
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

```jsx
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

```jsx
<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](LICENSE).

## 🔗 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