@synotech/flags

A comprehensive cross-platform library providing 500+ circular SVG flags for both React Native and React.js applications. Features country flags, language flags, and fictional flags with crisp, scalable vector graphics that look perfect on any device.

🚀 Cross-Platform Support

This library now supports both platforms:

• React Native: Uses react-native-svg for mobile apps
• React.js: Uses native SVG elements for web applications
• Automatic Platform Detection: The library automatically selects the correct implementation

🌍 What's Included

• 🏳️ 400+ Country & Territory Flags: Complete collection including ISO codes, territories, and regional variants
• 🗣️ 190+ Language Flags: Visual representation for different languages and locales
• 🏴‍☠️ Fictional Flags: Fun flags for pirates, science fiction, and fantasy themes
• 🎯 Optimized Performance: Built-in caching and memoization for smooth rendering
• 📱 React Native Ready: Designed specifically for mobile applications
• 🌐 Web Compatible: Full support for React.js web applications

📋 Prerequisites

For React Native

⚠️ Required Peer Dependencies

This library requires react-native-svg to be installed and configured in your React Native project:

npm install react-native-svg
# or
yarn add react-native-svg

# For React Native 0.60+ (auto-linking)
cd ios && pod install

# Follow the complete setup guide at:
# https://github.com/software-mansion/react-native-svg

For React.js

No additional dependencies required! The library uses native SVG elements for web applications.

🚀 Installation

npm install @synotech/flags
# or
yarn add @synotech/flags

📖 Basic Usage

The library automatically detects your platform and uses the appropriate implementation.

React Native Usage

import React from 'react';
import { View } from 'react-native';
import { Flag } from '@synotech/flags';

const MyComponent = () => {
  return (
    <View>
      {/* Display US flag */}
      <Flag code="us" width={40} height={40} />
      
      {/* Display UK flag */}
      <Flag code="gb" width={32} height={32} />
      
      {/* Using size prop (applies to both width and height) */}
      <Flag code="ca" size={48} />
    </View>
  );
};

React.js Usage

import React from 'react';
import { Flag } from '@synotech/flags';

const MyComponent = () => {
  return (
    <div>
      {/* Display US flag */}
      <Flag code="us" width={40} height={40} />
      
      {/* Display UK flag */}
      <Flag code="gb" width={32} height={32} />
      
      {/* Using size prop (applies to both width and height) */}
      <Flag code="ca" size={48} />
    </div>
  );
};

Explicit Platform Import

If you need to explicitly import for a specific platform:

// For React Native
import { Flag } from '@synotech/flags/react-native';

// For React.js
import { Flag } from '@synotech/flags';

Direct Component Import

For better tree-shaking and performance, import specific flag components directly:

import React from 'react';
import { View } from 'react-native';
import { Us, Gb, Ca, De, Fr, Jp } from '@synotech/flags';

const FlagGrid = () => {
  return (
    <View style={{ flexDirection: 'row', flexWrap: 'wrap' }}>
      <Us width={40} height={40} />
      <Gb width={40} height={40} />
      <Ca width={40} height={40} />
      <De width={40} height={40} />
      <Fr width={40} height={40} />
      <Jp width={40} height={40} />
    </View>
  );
};

🗣️ Language Flags

Display language-specific flags for internationalization:

import React from 'react';
import { View } from 'react-native';
import { Languages } from '@synotech/flags';

const LanguageSelector = () => {
  return (
    <View>
      {/* English */}
      <Languages.En width={24} height={24} />
      
      {/* Spanish */}
      <Languages.Es width={24} height={24} />
      
      {/* French */}
      <Languages.Fr width={24} height={24} />
      
      {/* German */}
      <Languages.De width={24} height={24} />
      
      {/* Chinese */}
      <Languages.Zh width={24} height={24} />
      
      {/* Regional English variants */}
      <Languages.EnUs width={24} height={24} />  {/* US English */}
      <Languages.EnGb width={24} height={24} />  {/* UK English */}
      <Languages.EnAu width={24} height={24} />  {/* Australian English */}
      <Languages.EnCa width={24} height={24} />  {/* Canadian English */}
    </View>
  );
};

🏴‍☠️ Fictional Flags

Add some fun with fictional and themed flags:

import React from 'react';
import { View } from 'react-native';
import { Fictional } from '@synotech/flags';

const ThemedFlags = () => {
  return (
    <View>
      {/* Pirate theme */}
      <Fictional.Pirate width={32} height={32} />
      <Fictional.JollyRoger width={32} height={32} />
      
      {/* Science fiction */}
      <Fictional.Klingon width={32} height={32} />
    </View>
  );
};

🌏 Regional & Territory Flags

Access flags for specific regions, states, and territories:

import React from 'react';
import { View } from 'react-native';
import { 
  // US States
  UsCa, UsNy, UsTx, UsFl,
  // Australian States
  AuNsw, AuVic, AuQld, AuWa,
  // UK Regions
  GbEng, GbSct, GbWls, GbNir,
  // Spanish Regions
  EsCt, EsPv, EsGa,
  // Other territories
  CnHk, // Hong Kong
  FrCp, // Corsica
} from '@synotech/flags';

const RegionalFlags = () => {
  return (
    <View>
      {/* US States */}
      <UsCa width={32} height={32} />  {/* California */}
      <UsTx width={32} height={32} />  {/* Texas */}
      
      {/* Australian States */}
      <AuNsw width={32} height={32} /> {/* New South Wales */}
      <AuVic width={32} height={32} /> {/* Victoria */}
      
      {/* UK Countries */}
      <GbEng width={32} height={32} /> {/* England */}
      <GbSct width={32} height={32} /> {/* Scotland */}
    </View>
  );
};

🎨 Styling & Customization

All flag components accept standard SVG props for full customization:

import React from 'react';
import { View } from 'react-native';
import { Flag } from '@synotech/flags';

const StyledFlags = () => {
  return (
    <View>
      {/* Custom dimensions */}
      <Flag code="us" width={60} height={40} />
      
      {/* With opacity */}
      <Flag code="gb" width={40} height={40} style={{ opacity: 0.7 }} />
      
      {/* With rotation */}
      <Flag 
        code="fr" 
        width={40} 
        height={40} 
        style={{ transform: [{ rotate: '45deg' }] }}
      />
      
      {/* With custom positioning */}
      <Flag 
        code="de" 
        width={40} 
        height={40} 
        style={{ 
          position: 'absolute',
          top: 20,
          left: 20,
        }}
      />
    </View>
  );
};

⚡ Performance Optimization

Pre-caching Flags

For better performance when displaying many flags, use the pre-caching feature:

import React, { useEffect } from 'react';
import { View } from 'react-native';
import { precacheFlagComponents, FlagsCache } from '@synotech/flags';

const OptimizedApp = () => {
  useEffect(() => {
    // Pre-cache all flag components
    const cachedFlags = precacheFlagComponents();
    console.log(`Cached ${Object.keys(cachedFlags).length} flags`);
  }, []);

  return (
    <View>
      {/* This component pre-renders all flags invisibly for better performance */}
      <FlagsCache size={24} />
      
      {/* Your regular app content */}
      <YourAppContent />
    </View>
  );
};

Memoized Flag Lists

When displaying flag lists, use React.memo for better performance:

import React, { memo } from 'react';
import { FlatList } from 'react-native';
import { Flag } from '@synotech/flags';

const FlagItem = memo(({ countryCode, name }) => (
  <View style={styles.flagItem}>
    <Flag code={countryCode} width={32} height={32} />
    <Text>{name}</Text>
  </View>
));

const CountryList = ({ countries }) => {
  return (
    <FlatList
      data={countries}
      keyExtractor={(item) => item.code}
      renderItem={({ item }) => (
        <FlagItem countryCode={item.code} name={item.name} />
      )}
    />
  );
};

🔤 Available Flag Categories

Country Flags (400+)

Standard ISO country codes and territories:

// Major countries
Us, Gb, De, Fr, Jp, Cn, In, Br, Au, Ca, Ru, Za

// European countries
Es, It, Nl, Se, No, Dk, Fi, Pl, Cz, Hu, Pt, Gr, At, Be, Ch

// Asian countries
Jp, Cn, In, Kr, Th, Vn, Id, My, Sg, Ph, Pk, Bd, Lk, Mm

// African countries
Za, Ng, Eg, Ke, Et, Gh, Ug, Tz, Zw, Bw, Mw, Zm

// And many more...

Language Flags (190+)

ISO 639 language codes:

// Major languages
En, Es, Fr, De, Zh, Ja, Ko, Ar, Hi, Ru, Pt, It

// Regional variants
EnUs, EnGb, EnAu, EnCa, EnIn, EnZa
EsMx, PtBr, FrCa

// Less common languages
Yi, Vo, Eo, La, Gd, Cy, Mt, Eu, Br

Special & Historical Flags

// Organizations
Un, Eu, Nato, Olympics, UnitedNations, EuropeanUnion

// Historical
SovietUnion, Yu

// Cultural/Ethnic
Sami, Maori, Wiphala, Guarani, Quechua, Otomi

// Astronomical
Earth, Mars

// Disputed territories
Xk, NorthernCyprus, Transnistria, SouthOssetia

📱 Platform Compatibility

• ✅ iOS
• ✅ Android
• ✅ Web (React Native Web)
• ✅ React Native 0.60+

🎯 Use Cases & Examples

1. Country Selection Dropdown

import React, { useState } from 'react';
import { View, TouchableOpacity, Text, Modal, FlatList } from 'react-native';
import { Flag } from '@synotech/flags';

const countries = [
  { code: 'us', name: 'United States' },
  { code: 'gb', name: 'United Kingdom' },
  { code: 'de', name: 'Germany' },
  { code: 'fr', name: 'France' },
  // ... more countries
];

const CountryPicker = ({ onSelect }) => {
  const [visible, setVisible] = useState(false);
  const [selected, setSelected] = useState(countries[0]);

  const handleSelect = (country) => {
    setSelected(country);
    setVisible(false);
    onSelect?.(country);
  };

  return (
    <View>
      <TouchableOpacity onPress={() => setVisible(true)}>
        <View style={styles.selector}>
          <Flag code={selected.code} width={24} height={24} />
          <Text>{selected.name}</Text>
        </View>
      </TouchableOpacity>

      <Modal visible={visible} animationType="slide">
        <FlatList
          data={countries}
          keyExtractor={(item) => item.code}
          renderItem={({ item }) => (
            <TouchableOpacity onPress={() => handleSelect(item)}>
              <View style={styles.option}>
                <Flag code={item.code} width={32} height={32} />
                <Text>{item.name}</Text>
              </View>
            </TouchableOpacity>
          )}
        />
      </Modal>
    </View>
  );
};

2. Language Switcher

import React, { useState } from 'react';
import { View, TouchableOpacity } from 'react-native';
import { Languages } from '@synotech/flags';

const languages = [
  { code: 'en', flag: 'En', name: 'English' },
  { code: 'es', flag: 'Es', name: 'Español' },
  { code: 'fr', flag: 'Fr', name: 'Français' },
  { code: 'de', flag: 'De', name: 'Deutsch' },
  { code: 'zh', flag: 'Zh', name: '中文' },
];

const LanguageSwitcher = ({ currentLanguage, onLanguageChange }) => {
  return (
    <View style={styles.languageBar}>
      {languages.map((language) => {
        const FlagComponent = Languages[language.flag];
        return (
          <TouchableOpacity
            key={language.code}
            onPress={() => onLanguageChange(language.code)}
            style={[
              styles.languageButton,
              currentLanguage === language.code && styles.active
            ]}
          >
            <FlagComponent width={20} height={20} />
          </TouchableOpacity>
        );
      })}
    </View>
  );
};

3. Sports App - Country Standings

import React from 'react';
import { View, Text, FlatList } from 'react-native';
import { Flag } from '@synotech/flags';

const CountryStandings = ({ standings }) => {
  const renderStanding = ({ item, index }) => (
    <View style={styles.standingRow}>
      <Text style={styles.position}>{index + 1}</Text>
      <Flag code={item.countryCode} width={28} height={28} />
      <Text style={styles.countryName}>{item.country}</Text>
      <Text style={styles.points}>{item.points}</Text>
    </View>
  );

  return (
    <FlatList
      data={standings}
      keyExtractor={(item) => item.countryCode}
      renderItem={renderStanding}
    />
  );
};

4. International News App

import React from 'react';
import { View, Text, Image, TouchableOpacity } from 'react-native';
import { Flag } from '@synotech/flags';

const NewsCard = ({ article }) => (
  <TouchableOpacity style={styles.card}>
    <Image source={{ uri: article.image }} style={styles.image} />
    <View style={styles.content}>
      <View style={styles.header}>
        <Flag code={article.countryCode} width={20} height={20} />
        <Text style={styles.country}>{article.country}</Text>
        <Text style={styles.time}>{article.timeAgo}</Text>
      </View>
      <Text style={styles.title}>{article.title}</Text>
      <Text style={styles.summary}>{article.summary}</Text>
    </View>
  </TouchableOpacity>
);

5. User Profile with Multiple Nationalities

import React from 'react';
import { View, Text } from 'react-native';
import { Flag } from '@synotech/flags';

const UserProfile = ({ user }) => (
  <View style={styles.profile}>
    <Text style={styles.name}>{user.name}</Text>
    
    <View style={styles.nationalitiesSection}>
      <Text style={styles.label}>Nationalities:</Text>
      <View style={styles.flagsContainer}>
        {user.nationalities.map((nationality) => (
          <Flag 
            key={nationality} 
            code={nationality} 
            width={24} 
            height={24} 
            style={styles.nationalityFlag}
          />
        ))}
      </View>
    </View>
    
    <View style={styles.languagesSection}>
      <Text style={styles.label}>Languages:</Text>
      <View style={styles.flagsContainer}>
        {user.languages.map((language) => (
          <Languages[language] 
            key={language} 
            width={20} 
            height={20} 
            style={styles.languageFlag}
          />
        ))}
      </View>
    </View>
  </View>
);

🔍 Flag Code Reference

Quick Country Code Examples

// Common country codes (ISO 3166-1 alpha-2)
'us' // United States
'gb' // United Kingdom  
'de' // Germany
'fr' // France
'jp' // Japan
'cn' // China
'in' // India
'br' // Brazil
'au' // Australia
'ca' // Canada
'mx' // Mexico
'ru' // Russia
'za' // South Africa
'ng' // Nigeria
'eg' // Egypt
'ar' // Argentina
'cl' // Chile
'pe' // Peru
'kr' // South Korea
'th' // Thailand
'id' // Indonesia
'my' // Malaysia
'sg' // Singapore
'ph' // Philippines
'vn' // Vietnam
'ua' // Ukraine
'pl' // Poland
'es' // Spain
'it' // Italy
'pt' // Portugal
'nl' // Netherlands
'be' // Belgium
'ch' // Switzerland
'at' // Austria
'se' // Sweden
'no' // Norway
'dk' // Denmark
'fi' // Finland

Language Code Examples

// Common language codes (ISO 639-1)
'en' // English
'es' // Spanish  
'fr' // French
'de' // German
'pt' // Portuguese
'it' // Italian
'ru' // Russian
'zh' // Chinese
'ja' // Japanese
'ko' // Korean
'ar' // Arabic
'hi' // Hindi
'tr' // Turkish
'pl' // Polish
'nl' // Dutch
'sv' // Swedish
'no' // Norwegian
'da' // Danish
'fi' // Finnish
'he' // Hebrew
'th' // Thai
'vi' // Vietnamese
'id' // Indonesian
'ms' // Malay
'tl' // Filipino/Tagalog
'uk' // Ukrainian
'cs' // Czech
'sk' // Slovak
'hu' // Hungarian
'ro' // Romanian
'bg' // Bulgarian
'hr' // Croatian
'sr' // Serbian
'sl' // Slovenian
'et' // Estonian
'lv' // Latvian
'lt' // Lithuanian
'mt' // Maltese
'ga' // Irish
'cy' // Welsh
'eu' // Basque
'ca' // Catalan
'gl' // Galician

🛠️ TypeScript Support

Full TypeScript support with proper type definitions:

import React from 'react';
import { Flag, FlagProps, Languages } from '@synotech/flags';
import { SvgProps } from 'react-native-svg';

interface CountryFlagProps extends FlagProps {
  countryCode: string;
  size?: number;
  onPress?: () => void;
}

const CountryFlag: React.FC<CountryFlagProps> = ({ 
  countryCode, 
  size = 32, 
  onPress,
  ...svgProps 
}) => {
  return (
    <Flag 
      code={countryCode}
      width={size}
      height={size}
      {...svgProps}
    />
  );
};

🐛 Troubleshooting

Common Issues

1. Flags not showing up

   # Make sure react-native-svg is properly installed
   npm install react-native-svg
   cd ios && pod install

2. TypeScript errors

   # Install type definitions
   npm install --save-dev @types/react-native-svg

3. Performance issues with many flags

   // Use direct imports instead of the main Flag component
   import { Us, Gb, De } from '@synotech/flags';
      
   // Or use pre-caching
   import { precacheFlagComponents } from '@synotech/flags';

4. Flag not found

   // Always use lowercase codes
   <Flag code="us" />  // ✅ Correct
   <Flag code="US" />  // ❌ Incorrect

📊 Bundle Size

• Core library: ~50KB
• Individual flag components: ~1-2KB each
• Language flags: ~1KB each
• Total if importing all flags: ~800KB

Recommendation: Import only the flags you need for optimal bundle size.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License. © Synoptic Technologies 2023

🙏 Acknowledgments

• Flag designs based on Circle Flags
• Built with react-native-svg
• Created by Synotech

📞 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions