# IconsFlag

250+ country flag icons named with ISO 3166-1 alpha-2 codes (`FlagUS`, `FlagGB`, `FlagDE`, ...) and rendered as scalable SVGs.

## Installation

```bash
npm install @xsolla/xui-icons-flag
```

## Imports

```tsx
import { FlagUS, FlagGB, FlagDE, FlagJP, type FlagIconProps } from '@xsolla/xui-icons-flag';
```

## Quick start

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

export default function QuickStart() {
  return <FlagUS size={24} aria-label="United States" />;
}
```

## API Reference

### Flag components (`<FlagUS>`, `<FlagGB>`, ...)

All flag components accept the same props (`FlagIconProps`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `number` | `24` | Pixel size (square). |
| `className` | `string` | — | CSS class on the wrapper. |
| `style` | `CSSProperties` | — | Inline styles. |
| `data-testid` | `string` | — | Test ID (web). |
| `testID` | `string` | — | Test ID (React Native). |
| `aria-label` | `string` | — | Accessible label (e.g. country name). When set, the icon is exposed as `role="img"`. |
| `aria-hidden` | `boolean` | `true` if no `aria-label` | Hide from assistive tech. |

This package does not consume `ThemeOverrideProps`.

> `FlagIcon` is also exported but is an internal wrapper used to build each `Flag<CC>` component from a raw SVG string. Most consumers should use the named flag components.

## Available flags

Flag components are named `Flag` + ISO 3166-1 alpha-2 code. Examples: `FlagUS`, `FlagGB`, `FlagDE`, `FlagFR`, `FlagJP`, `FlagBR`, `FlagIN`, `FlagAU`, `FlagCA`, `FlagMX`, `FlagZA`, `FlagZW`.

A few codes appear with numeric suffixes (e.g. `FlagBQ`, `FlagBQ1`, `FlagBQ2`) where multiple flag variants exist for the same code.

For the full list of 250+ flags, see `packages/foundation/icons-flag/src/index.ts`.

## Examples

### Sizing

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

export default function Sizes() {
  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
      <FlagUS size={16} aria-label="US, small" />
      <FlagUS size={24} aria-label="US" />
      <FlagUS size={32} aria-label="US, large" />
      <FlagUS size={48} aria-label="US, extra large" />
    </div>
  );
}
```

### 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}
          type="button"
          onClick={() => setSelected(code)}
          aria-pressed={selected === 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>
  );
}
```

### Dynamic lookup by ISO code

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

export default function DynamicFlag({ code }: { code: string }) {
  const FlagComponent = (Flags as Record<string, React.FC<FlagIconProps>>)[`Flag${code.toUpperCase()}`];
  return FlagComponent ? <FlagComponent size={24} aria-label={code} /> : null;
}
```

## Accessibility

- Flags are hidden from screen readers by default.
- When the flag conveys meaning (e.g. country picker), set `aria-label` to the country name.
- Within a labelled control, keep the flag `aria-hidden` and label the control.
