SVG Flags

A comprehensive collection of SVG country flags for web applications. This package provides high-quality, scalable flag icons that can be easily integrated into React applications.

Features

• 🚩 224 Country Flags: Complete collection of world flags in SVG format
• ⚡ Lightweight: Optimized SVG files for fast loading
• 🎨 Customizable: Easy to style and resize
• ♿ Accessible: Built with accessibility in mind
• 🔍 Searchable: Includes country search functionality
• 📱 Responsive: Works great on all devices
• 🎯 TypeScript: Full TypeScript support with type definitions
• ⚛️ React 19: Compatible with React 19 and all modern React versions

Installation

npm install svg-flags
# or
yarn add svg-flags
# or
pnpm add svg-flags

⚡ Instant Loading (No Setup Required!)

The package now includes embedded SVG content for instant loading. No setup required!

• 🚀 Zero HTTP requests - All flags load instantly
• 📦 No file copying - Everything is included in the package
• ⚡ Perfect for tables - 100+ flags load in milliseconds
• 🎯 No 404 errors - All flags are guaranteed to work

Legacy Setup (Optional)

If you prefer the old approach with external files:

# Run this command in your project root
npx svg-flags setup-flags

This will copy all 224 flag SVG files to your project's public/flags/ directory.

Quick Start

import { Flag } from "svg-flags";

function App() {
  return (
    <div>
      <Flag country="us" width={32} />
      <Flag country="gb" width={48} height={32} />
      <Flag country="fr" width={64} showBorder />

      {/* Custom fallback for invalid country codes */}
      <Flag country="invalid" fallback="🏳️" />
      <Flag country="unknown" fallback="❓" />
    </div>
  );
}

Components

Flag

The main component for displaying country flags.

import { Flag } from "svg-flags";

<Flag
  country="us" // Country code (required)
  width={32} // Width in pixels (default: 32)
  height={24} // Height in pixels (optional)
  className="my-flag" // CSS class name
  style={{ margin: 8 }} // Inline styles
  alt="US Flag" // Alt text for accessibility
  clickable={true} // Make flag clickable
  onClick={(country) => console.log(country)}
  showBorder={true} // Show border around flag
  borderColor="#ccc" // Border color
  borderWidth={1} // Border width
  fallback="🏳️" // Custom fallback for invalid country codes
/>;

FlagSelector

A dropdown component for selecting countries with search functionality.

import { FlagSelector } from "svg-flags";

function CountrySelector() {
  const [selectedCountry, setSelectedCountry] = useState("us");

  return (
    <FlagSelector
      value={selectedCountry}
      onChange={setSelectedCountry}
      placeholder="Search countries..."
      flagSize={24}
      showNames={true}
      showSearch={true}
      maxResults={50}
    />
  );
}

API Reference

Flag Props

FlagSelector Props

Utilities

The package also exports utility functions for working with flags:

import {
  normalizeCountryCode,
  isValidCountryCode,
  getCountryInfo,
  searchCountries,
  getAvailableCountryCodes,
} from "svg-flags";

// Normalize country code
const code = normalizeCountryCode("US"); // 'us'

// Validate country code
const isValid = isValidCountryCode("us"); // true

// Get country information
const info = getCountryInfo("us");
// { code: 'us', name: 'United States', ... }

// Search countries
const results = searchCountries("united");
// Returns array of countries matching the search

// Get all available country codes
const codes = getAvailableCountryCodes();
// ['us', 'gb', 'fr', ...]

Available Countries

The package includes flags for 224 countries and territories:

• North America: US, CA, MX, and more
• Europe: GB, FR, DE, IT, ES, and more
• Asia: CN, JP, KR, IN, and more
• Africa: ZA, EG, NG, and more
• South America: BR, AR, CL, and more
• Oceania: AU, NZ, and more

Styling

Flags can be styled using CSS classes or inline styles:

// Using CSS classes
<Flag country="us" className="my-flag" />

// Using inline styles
<Flag
  country="us"
  style={{
    borderRadius: '4px',
    boxShadow: '0 2px 4px rgba(0,0,0,0.1)'
  }}
/>

Accessibility

The package includes built-in accessibility features:

• ARIA labels for screen readers
• Keyboard navigation support
• High contrast support
• Alt text for images

Performance

• SVG files are optimized for size
• Lazy loading support
• Efficient rendering with React
• Minimal bundle size impact

React Compatibility

This package is fully compatible with:

• React 19 ✅
• React 18 ✅
• React 17 ✅
• React 16.8+ ✅ (with hooks support)

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

Troubleshooting

Flags Not Loading (404 Errors)

If you see 404 errors in the browser console when trying to load flags, make sure you've run the setup command:

npx svg-flags setup-flags

This copies the SVG files to your project's public/flags/ directory.

Manual Setup

If the automatic setup doesn't work, manually copy the flag files:

1. Find the flags directory in node_modules/svg-flags/
2. Copy all .svg files to your project's public/flags/ directory
3. Ensure your web server serves static files from the public directory

Next.js Projects

For Next.js projects, make sure your next.config.js includes:

module.exports = {
  // ... other config
  async rewrites() {
    return [
      {
        source: "/flags/:path*",
        destination: "/flags/:path*",
      },
    ];
  },
};

Vite Projects

For Vite projects, the files should be accessible automatically if placed in the public directory.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Changelog

1.0.0

• Initial release
• 224 country flags
• React components
• TypeScript support
• Search functionality
• Accessibility features