Coat of Arms 🏛️

A modern, lightweight React library for displaying country coat of arms and flags with built-in CSS styling. Perfect for building international applications with beautiful heraldic symbols.

✨ Features

• 🏛️ 210+ Country Coat of Arms - High-quality SVG coat of arms for all countries
• 🚩 Flag Icons - Beautiful flag icons with multiple size options
• ⚡ Zero Configuration - Works out of the box with automatic CSS injection
• 🎨 Customizable Sizes - 11 predefined sizes from 2xs to 6xl
• 🔄 Lazy Loading - Intersection Observer API for performance optimization
• 📦 Tiny Bundle - Minimal footprint with tree-shaking support
• 💪 TypeScript - Full type safety with TypeScript definitions
• ⚛️ React Optimized - Built specifically for React applications
• 🎯 Accessibility - ARIA labels and semantic HTML

📦 Installation

npm install coat-of-arms

Or with yarn:

yarn add coat-of-arms

Or with pnpm:

pnpm add coat-of-arms

🚀 Quick Start

Basic Usage

import { Coat, Flag } from 'coat-of-arms';

function App() {
  return (
    <div>
      {/* Display coat of arms */}
      <Coat country="US" size="lg" />
      
      {/* Display flag */}
      <Flag country="US" size="lg" />
    </div>
  );
}

That's it! The CSS is automatically injected, no additional setup needed.

📖 Components

<Coat /> - Coat of Arms Component

Display country coat of arms with customizable sizes and styles.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | country | string | required | ISO2 country code (e.g., 'US', 'GB', 'UZ') | | size | '2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl' \| '5xl' \| '6xl' | 'md' | Size of the coat of arms | | className | string | '' | Additional CSS classes | | style | React.CSSProperties | {} | Inline styles | | lazy | boolean | false | Enable lazy loading with Intersection Observer | | onError | (error: Error) => void | undefined | Error callback function | | alt | string | '{country} coat of arms' | Alt text for accessibility |

Examples

Basic Usage:

<Coat country="US" />

With Custom Size:

<Coat country="GB" size="xl" />

With Lazy Loading:

<Coat 
  country="FR" 
  size="lg" 
  lazy={true} 
/>

With Custom Styling:

<Coat 
  country="DE" 
  size="2xl"
  className="my-coat"
  style={{
    border: '2px solid gold',
    borderRadius: '8px',
    padding: '10px',
    boxShadow: '0 4px 12px rgba(0,0,0,0.15)'
  }}
/>

With Error Handling:

<Coat 
  country="UZ" 
  onError={(error) => {
    console.error('Failed to load:', error);
  }}
/>

<Flag /> - Flag Component

Display country flags with customizable sizes and border radius.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | country | string | required | ISO2 country code (e.g., 'US', 'GB', 'UZ') | | size | 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' | 'md' | Size of the flag | | radius | 'sm' \| 'md' \| 'lg' | 'md' | Border radius size | | className | string | '' | Additional CSS classes | | style | React.CSSProperties | {} | Inline styles |

Examples

Basic Usage:

<Flag country="US" />

Different Sizes:

<Flag country="GB" size="sm" />
<Flag country="FR" size="md" />
<Flag country="DE" size="lg" />
<Flag country="IT" size="xl" />
<Flag country="ES" size="2xl" />

With Border Radius:

<Flag country="JP" size="lg" radius="lg" />

Custom Styling:

<Flag 
  country="CA" 
  size="xl"
  radius="sm"
  className="shadow-lg"
  style={{
    border: '3px solid white',
    boxShadow: '0 4px 8px rgba(0,0,0,0.2)'
  }}
/>

🎯 Real-World Examples

Country Selector

import { Coat, Flag } from 'coat-of-arms';
import { useState } from 'react';

function CountrySelector() {
  const [selected, setSelected] = useState('US');
  const countries = ['US', 'GB', 'FR', 'DE', 'IT', 'ES', 'JP', 'CN', 'UZ'];

  return (
    <div>
      <div style={{ display: 'flex', gap: '10px', marginBottom: '20px' }}>
        {countries.map(code => (
          <button
            key={code}
            onClick={() => setSelected(code)}
            style={{
              padding: '8px',
              border: selected === code ? '2px solid blue' : '1px solid gray',
              borderRadius: '4px',
              cursor: 'pointer'
            }}
          >
            <Flag country={code} size="sm" />
          </button>
        ))}
      </div>
      
      <div style={{ textAlign: 'center' }}>
        <h2>{selected}</h2>
        <Coat country={selected} size="2xl" />
      </div>
    </div>
  );
}

Country Card Component

import { Coat, Flag } from 'coat-of-arms';

function CountryCard({ code, name, capital, population }) {
  return (
    <div style={{
      border: '1px solid #ddd',
      borderRadius: '12px',
      padding: '20px',
      maxWidth: '300px',
      boxShadow: '0 2px 8px rgba(0,0,0,0.1)'
    }}>
      <div style={{ display: 'flex', alignItems: 'center', gap: '15px', marginBottom: '15px' }}>
        <Flag country={code} size="lg" radius="sm" />
        <h2 style={{ margin: 0 }}>{name}</h2>
      </div>
      
      <div style={{ textAlign: 'center', marginBottom: '15px' }}>
        <Coat country={code} size="xl" />
      </div>
      
      <div style={{ fontSize: '14px', color: '#666' }}>
        <p><strong>Capital:</strong> {capital}</p>
        <p><strong>Population:</strong> {population}</p>
      </div>
    </div>
  );
}

// Usage
<CountryCard 
  code="UZ" 
  name="Uzbekistan" 
  capital="Tashkent" 
  population="34 million" 
/>

Lazy Loading Gallery

import { Coat } from 'coat-of-arms';

function CoatGallery() {
  const countries = ['US', 'GB', 'FR', 'DE', 'IT', 'ES', 'JP', 'CN', 'RU', 'BR', 'IN', 'UZ'];

  return (
    <div style={{
      display: 'grid',
      gridTemplateColumns: 'repeat(auto-fill, minmax(150px, 1fr))',
      gap: '20px',
      padding: '20px'
    }}>
      {countries.map(code => (
        <div key={code} style={{ textAlign: 'center' }}>
          <Coat 
            country={code} 
            size="lg" 
            lazy={true}  // Only loads when visible
          />
          <p style={{ marginTop: '10px', fontSize: '14px' }}>{code}</p>
        </div>
      ))}
    </div>
  );
}

With TypeScript

import { Coat, Flag, CoatProps, FlagProps, useCoatOfArms } from 'coat-of-arms';
import { FC } from 'react';

interface CountryDisplayProps {
  countryCode: string;
  showCoat?: boolean;
  showFlag?: boolean;
}

const CountryDisplay: FC<CountryDisplayProps> = ({ 
  countryCode, 
  showCoat = true, 
  showFlag = true 
}) => {
  const { path, loading, error } = useCoatOfArms(countryCode);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <div>
      {showCoat && <Coat country={countryCode} size="lg" />}
      {showFlag && <Flag country={countryCode} size="md" radius="sm" />}
    </div>
  );
};

export default CountryDisplay;

🌍 Supported Countries

The library includes 214+ countries with coat of arms and flags. Use standard ISO 3166-1 alpha-2 country codes:

| Region | Countries | |--------|-----------| | Americas | US, CA, BR, MX, AR, CL, CO, PE, VE, UY, and more | | Europe | GB, DE, FR, IT, ES, RU, PL, NL, BE, CH, and more | | Asia | CN, JP, IN, KR, UZ, KZ, TH, VN, PH, ID, and more | | Africa | ZA, EG, NG, KE, ET, GH, TZ, UG, MA, DZ, and more | | Oceania | AU, NZ, FJ, PG, WS, TO, VU, KI, and more |

View complete list of supported countries →

⚡ Performance

• 🚀 Lazy Loading - Uses Intersection Observer API to load only visible components
• 💾 CSS Injection - Automatic CSS injection, no manual setup required
• 📦 Tree Shaking - Only bundle what you use
• ⚡ Fast Rendering - CSS-based rendering for optimal performance
• 🎯 O(1) Lookup - Instant country code validation

🎨 Size Reference

Visual guide for coat of arms sizes:

| Size | Dimensions | Use Case | |------|------------|----------| | 2xs | ~16px | Tiny icons, badges | | xs | ~24px | Small icons | | sm | ~32px | Compact displays | | md | ~48px | Default size | | lg | ~64px | Medium displays | | xl | ~96px | Large displays | | 2xl | ~128px | Hero sections | | 3xl | ~160px | Feature displays | | 4xl | ~192px | Prominent displays | | 5xl | ~224px | Extra large | | 6xl | ~256px | Maximum size |

🔧 Framework Integration

Next.js App Router

// app/countries/page.tsx
import { Coat, Flag } from 'coat-of-arms';

export default function CountriesPage() {
  return (
    <div>
      <h1>Countries</h1>
      <Coat country="US" size="xl" />
      <Flag country="US" size="lg" />
    </div>
  );
}

Next.js Pages Router

// pages/countries.js
import { Coat, Flag } from 'coat-of-arms';

export default function Countries() {
  return (
    <div>
      <Coat country="UZ" size="xl" />
      <Flag country="UZ" size="lg" />
    </div>
  );
}

Vite + React

// src/App.jsx
import { Coat, Flag } from 'coat-of-arms';

function App() {
  return (
    <div className="App">
      <Coat country="FR" size="2xl" />
      <Flag country="FR" size="xl" />
    </div>
  );
}

export default App;

Create React App

// src/App.js
import { Coat, Flag } from 'coat-of-arms';

function App() {
  return (
    <div className="App">
      <Coat country="DE" size="lg" />
      <Flag country="DE" size="md" />
    </div>
  );
}

export default App;

Remix

// app/routes/countries.tsx
import { Coat, Flag } from 'coat-of-arms';

export default function Countries() {
  return (
    <div>
      <Coat country="GB" size="xl" />
      <Flag country="GB" size="lg" />
    </div>
  );
}

🎯 Best Practices

1. Use Lazy Loading for Long Lists

function CountryList({ countries }) {
  return (
    <div>
      {countries.map(code => (
        <Coat 
          key={code}
          country={code} 
          size="md" 
          lazy={true}  // ✅ Good for performance
        />
      ))}
    </div>
  );
}

2. Handle Errors Gracefully

<Coat 
  country={userInput} 
  onError={(error) => {
    console.error('Invalid country code:', error);
    // Show fallback UI
  }}
/>

3. Use Appropriate Sizes

// ✅ Good - appropriate sizes for context
<Coat country="US" size="sm" />  // In a list
<Coat country="US" size="xl" />  // Hero section
<Coat country="US" size="6xl" /> // Landing page

// ❌ Avoid - too large for context
<Coat country="US" size="6xl" />  // In a table cell

4. Combine with Flags

function CountryHeader({ code, name }) {
  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: '15px' }}>
      <Flag country={code} size="lg" radius="sm" />
      <h1>{name}</h1>
      <Coat country={code} size="md" />
    </div>
  );
}

🐛 Troubleshooting

CSS Not Loading

The CSS is automatically injected when you import the components. If styles aren't working:

// ✅ Correct - import from main package
import { Coat, Flag } from 'coat-of-arms';

// ❌ Wrong - don't import from subdirectories
import { Coat } from 'coat-of-arms/dist/components/Coat';

TypeScript Errors

Make sure you have React types installed:

npm install --save-dev @types/react

Images Not Showing

Verify the country code is valid (2-letter ISO code):

// ✅ Correct
<Coat country="US" />
<Coat country="GB" />

// ❌ Wrong
<Coat country="USA" />  // Should be "US"
<Coat country="UK" />   // Should be "GB"

⭐ Support

If you find this package useful, please consider:

• ⭐ Starring the repository on GitHub
• 🐛 Reporting bugs and issues
• 💡 Suggesting new features
• 📖 Improving documentation

📧 Contact

• GitHub: @islomjon ergashev
• NPM: coat-of-arms

Made with ❤️ for the React community