# Icons Flag

A cross-platform React flag icons package containing 250+ country flags. Each flag uses ISO 3166-1 alpha-2 country codes and renders as a scalable SVG.

## Installation

```bash
npm install @xsolla/xui-icons-flag
# or
yarn add @xsolla/xui-icons-flag
```

## Demo

### Individual Flag Import

```tsx
import * as React from 'react';
import { FlagUS, FlagGB, FlagDE, FlagJP } from '@xsolla/xui-icons-flag';

export default function IndividualFlags() {
  return (
    <div style={{ display: 'flex', gap: 8 }}>
      <FlagUS size={24} />
      <FlagGB size={24} />
      <FlagDE size={24} />
      <FlagJP size={24} />
    </div>
  );
}
```

### Dynamic Flag Component

```tsx
import * as React from 'react';
import { FlagIcon } from '@xsolla/xui-icons-flag';
import * as Flags from '@xsolla/xui-icons-flag';

export default function DynamicFlag() {
  const countryCode = 'US';
  const FlagComponent = Flags[`Flag${countryCode}`];

  return FlagComponent ? <FlagComponent size={24} /> : null;
}
```

### Flag Sizes

```tsx
import * as React from 'react';
import { FlagUS } from '@xsolla/xui-icons-flag';

export default function FlagSizes() {
  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
      <FlagUS size={16} />
      <FlagUS size={24} />
      <FlagUS size={32} />
      <FlagUS size={48} />
    </div>
  );
}
```

## Anatomy

```jsx
import { FlagUS } from '@xsolla/xui-icons-flag';

<FlagUS
  size={24}                   // Size in pixels
  className="flag"            // CSS class
  style={{ margin: 4 }}       // Inline styles
  aria-label="United States"  // Accessible label
/>
```

## Examples

### Country Selector

```tsx
import * as React from 'react';
import { FlagUS, FlagGB, FlagDE, FlagFR, FlagJP } from '@xsolla/xui-icons-flag';

export default function CountrySelector() {
  const [selected, setSelected] = React.useState('US');

  const countries = [
    { code: 'US', name: 'United States', Flag: FlagUS },
    { code: 'GB', name: 'United Kingdom', Flag: FlagGB },
    { code: 'DE', name: 'Germany', Flag: FlagDE },
    { code: 'FR', name: 'France', Flag: FlagFR },
    { code: 'JP', name: 'Japan', Flag: FlagJP },
  ];

  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      {countries.map(({ code, name, Flag }) => (
        <button
          key={code}
          onClick={() => setSelected(code)}
          style={{
            display: 'flex',
            alignItems: 'center',
            gap: 12,
            padding: '8px 16px',
            background: selected === code ? '#e0e0e0' : 'transparent',
            border: 'none',
            cursor: 'pointer',
          }}
        >
          <Flag size={20} aria-hidden />
          <span>{name}</span>
        </button>
      ))}
    </div>
  );
}
```

### With InputPhone

```tsx
import * as React from 'react';
import { InputPhone, Country } from '@xsolla/xui-input-phone';
import { FlagUS, FlagGB, FlagDE } from '@xsolla/xui-icons-flag';

export default function PhoneWithFlags() {
  const [phone, setPhone] = React.useState('');
  const [country, setCountry] = React.useState<Country>();

  const countries: Country[] = [
    { code: 'US', name: 'United States', dialCode: '+1', flag: <FlagUS /> },
    { code: 'GB', name: 'United Kingdom', dialCode: '+44', flag: <FlagGB /> },
    { code: 'DE', name: 'Germany', dialCode: '+49', flag: <FlagDE /> },
  ];

  return (
    <InputPhone
      value={phone}
      onChange={(e) => setPhone(e.target.value)}
      countries={countries}
      selectedCountry={country}
      onCountryChange={setCountry}
    />
  );
}
```

## API Reference

### Flag Components

Each flag component (e.g., `FlagUS`, `FlagGB`) accepts the same props:

**FlagIconProps:**

| Prop | Type | Default | Description |
| :--- | :--- | :------ | :---------- |
| size | `number` | `24` | Size in pixels (width and height). |
| className | `string` | - | CSS class name. |
| style | `CSSProperties` | - | Inline styles. |
| data-testid | `string` | - | Test ID (web). |
| testID | `string` | - | Test ID (React Native). |
| aria-label | `string` | - | Accessible label. |
| aria-hidden | `boolean` | `true` if no aria-label | Hide from screen readers. |

## Available Flags

Flags are named using ISO 3166-1 alpha-2 country codes prefixed with "Flag":

| Code | Component | Country |
| :--- | :-------- | :------ |
| AD | `FlagAD` | Andorra |
| AE | `FlagAE` | United Arab Emirates |
| AF | `FlagAF` | Afghanistan |
| ... | ... | ... |
| US | `FlagUS` | United States |
| GB | `FlagGB` | United Kingdom |
| DE | `FlagDE` | Germany |
| FR | `FlagFR` | France |
| JP | `FlagJP` | Japan |
| ... | ... | ... |
| ZW | `FlagZW` | Zimbabwe |

Over 250 country flags are available. See the full list in the package source.

## Tree Shaking

Import individual flags for optimal bundle size:

```tsx
// Good - only imports US flag
import { FlagUS } from '@xsolla/xui-icons-flag';

// Avoid - imports all flags
import * as Flags from '@xsolla/xui-icons-flag';
```

## Accessibility

- Flags are hidden from screen readers by default (`aria-hidden="true"`)
- Use `aria-label` when the flag conveys meaningful information
- For decorative flags, keep the default hidden behavior
