Flags

v1.1.2

Documentation Under Review

Installation

Install the Flags component from the Catalyst component library:

npm install @pmi/catalyst-flag-icons

Overview

The Flags package provides a comprehensive collection of SVG flag icons for countries and territories worldwide. Each flag component is built on top of the BaseIcon component from @pmi/catalyst-icons, inheriting all sizing, coloring, and gradient capabilities while maintaining authentic flag designs.

Available Flags

The package includes 196+ flag components representing countries, territories, and international organizations including:

• Americas: USA, Canada, Mexico, Brazil, Argentina, Chile, Colombia, and more
• Europe: United Kingdom, Germany, France, Italy, Spain, Netherlands, and more
• Asia: China, Japan, India, South Korea, Thailand, Singapore, and more
• Africa: South Africa, Egypt, Nigeria, Kenya, Morocco, and more
• Oceania: Australia, New Zealand, Fiji, Papua New Guinea, and more
• International: European Union

Each flag is exported as a named component using its country/territory name in PascalCase (e.g., UnitedStates, UnitedKingdom, SaudiArabia).

Examples

Basic Usage

Display a flag with default settings (large size, original colors):

Size Variants

Flags support all BaseIcon size variants from extra small to extra large, plus a full size that adapts to parent dimensions:

Flag Gallery

Browse all available flag icons in the Catalyst Design System. Each flag is importable individually for optimal tree-shaking.

API Reference

All flag components accept the same props as BaseIcon from @pmi/catalyst-icons:

Size Scale Reference

Flag sizes use CSS variable-based scaling:

• xs: 16px × 16px
• sm: 20px × 20px
• md: 24px × 24px
• lg: 32px × 32px (default)
• xl: 40px × 40px
• full: 100% of parent width and height

Available Flag Components

Import flags using their country/territory name in PascalCase:

import {
  // Americas
  Usa,
  Canada,
  Mexico,
  Brazil,
  Argentina,
  Chile,
  Colombia,
  // Europe
  UnitedKingdom,
  Germany,
  France,
  Italy,
  Spain,
  Netherlands,
  // Asia
  China,
  Japan,
  India,
  SouthKorea,
  Thailand,
  Singapore,
  // Africa
  SouthAfrica,
  Egypt,
  Nigeria,
  Kenya,
  Morocco,
  // Oceania
  Australia,
  NewZealand,
  Fiji,
  // International
  EuropeanUnion,
  // ... and 170+ more
} from '@pmi/catalyst-flag-icons';

Accessibility

All flag components are built with accessibility in mind:

WCAG 2.1 AA Compliance

• Hidden from Screen Readers: Flags have aria-hidden="true" by default since they are typically decorative elements
• Semantic Context: When flags convey meaningful information, wrap them with descriptive text or labels
• Color Independence: Don't rely solely on flags to convey information; provide text labels or context
• Keyboard Navigation: Flag components are not interactive by default but can be wrapped in interactive elements

Best Practices

// ✅ Good: Flag with descriptive text
<div>
  <Usa className="inline-block mr-2" />
  <span>United States</span>
</div>

// ✅ Good: Flag in labeled button
<button aria-label="Select United States">
  <Usa />
</button>

// ❌ Avoid: Flag as sole information carrier
<button>
  <Usa />
</button>

Testing Considerations

Flag components include data-testid support for integration testing:

<Germany data-testid="country-flag-de" />

Design Tokens

Flags use the following design tokens from the Catalyst theme:

Size Tokens

• --scale-16: Extra small (xs)
• --scale-20: Small (sm)
• --scale-24: Medium (md)
• --scale-32: Large (lg)
• --scale-40: Extra large (xl)

Color Tokens (when overriding original colors)

• --icon-primary: Primary brand color
• --icon-secondary: Secondary color
• --icon-info: Informational blue
• --icon-danger: Error/danger red
• --icon-warning: Warning yellow
• --icon-success: Success green
• --icon-accent: Accent color
• --icon-white: White/light
• --icon-inverted: Inverted theme color
• --icon-neutral-soft: Soft neutral
• --icon-neutral-dark: Dark neutral

Technical Details

Component Generation

Flag components are auto-generated from SVG assets. Do not modify flag component files directly. Any changes should be made in the build script at ~/process-packages-assets.cjs.

Bundle Optimization

Each flag component is exported individually, enabling tree-shaking. Import only the flags you need to minimize bundle size:

// ✅ Optimal: Tree-shakeable imports
import { Usa, Canada, Mexico } from '@pmi/catalyst-flag-icons';

// ⚠️ Avoid: Wildcard imports prevent tree-shaking
import * as Flags from '@pmi/catalyst-flag-icons';

SVG Rendering

Flags use react-inlinesvg for SVG rendering, which:

• Enables runtime color and gradient manipulation
• Ensures unique IDs for multiple instances
• Supports CSS custom properties for theming

Related Components

• Icons - Base icon component system that flags extend
• Avatar - Can use flags to show user nationality
• Badge - Combine with flags for country indicators
• Select - Use in country/region selection dropdowns

See Also

• BaseIcon Component Documentation
• Icon Design Guidelines
• Accessibility Best Practices