Country Flag Icons

Ready for Production

Overview

The recommended approach for rendering country flags in Catalyst applications is the country-flag-icons package (MIT license, 3M+ weekly downloads, 0 dependencies).

This replaces the deprecated @pmi/catalyst-flag-icons package, which required the Catalyst team to manually maintain SVG assets and country code mappings.

Why country-flag-icons?

• Comprehensive coverage of all ISO 3166-1 country codes plus exceptional reservations (EU, XK, etc.)
• Built-in React components with TypeScript declarations
• Tree-shakeable individual imports (~1 KB per flag)
• SVG flags in 3:2 aspect ratio, optimized for small screen sizes
• Actively maintained by the open-source community
• Helper utilities (hasFlag, countries) for validation

Installation

npm install country-flag-icons

Examples

Basic Usage

Import flag components by their ISO 3166-1 alpha-2 country code:

Individual Imports (Tree-Shaking)

For smaller bundles, import each flag individually. This ensures your bundler only includes the flags you use:

// Named import (relies on tree-shaking)
import { US } from 'country-flag-icons/react/3x2';

// Individual import (guaranteed tree-shaking)
import US from 'country-flag-icons/react/3x2/US';

Custom Sizing

Flags render as inline SVGs. Control their size with standard CSS classes or inline styles:

Validating Country Codes

Use the hasFlag utility to check if a country code is supported before rendering:

Flag Gallery

Browse all available country flags. Each flag uses its ISO 3166-1 alpha-2 country code:

API Reference

React Components

Each flag is available as a React component from country-flag-icons/react/3x2:

Utility Functions

Supported Country Codes

The library supports all ISO 3166-1 alpha-2 country codes, plus:

• Exceptional reservations: EU (European Union), IC (Canary Islands), AC (Ascension Island), TA (Tristan da Cunha)
• User-assigned codes: XK (Kosovo), XA (Abkhazia), XO (South Ossetia), XC (Northern Cyprus)
• Subdivision codes: GB-ENG, GB-SCT, GB-WLS, GB-NIR, BQ-BO, BQ-SA, BQ-SE, ES-CT

Accessibility

Flag icons are inline SVGs, so their accessibility depends on how they are used. Decide whether each flag is informative or decorative in context.

Informative Flags

When the flag is the only way a user can identify the country (no visible text label nearby), it is informative and needs an accessible name:

{
  /* Flag is the sole identifier — title required */
}
<US title="United States" className="h-6" />;

Use the full country name ("United States", "United Kingdom") rather than the ISO code ("US", "GB"). Your application should pass a stable, pre-resolved country name through the title prop to avoid server/client rendering mismatches.

Decorative Flags

When the flag appears alongside a visible text label that already identifies the country, the flag is decorative and should be hidden from assistive technologies to avoid redundant announcements:

{
  /* Country name is already visible — flag is decorative */
}
<div className="flex items-center gap-2">
  <US aria-hidden="true" className="h-5" />
  <span>United States</span>
</div>;

Quick Decision Guide

Migration from @pmi/catalyst-flag-icons

Key Differences

Migration Examples

Before (deprecated):

import { Usa, UnitedKingdom, Germany } from '@pmi/catalyst-flag-icons';

<Usa size="lg" color="original" />
<UnitedKingdom size="md" color="original" />
<Germany size="sm" color="original" />

After (recommended):

import { US, GB, DE } from 'country-flag-icons/react/3x2';

<US title="United States" className="h-8" />
<GB title="United Kingdom" className="h-6" />
<DE title="Germany" className="h-5" />

Size Mapping Reference