Flutter Country Flags 🏳️ #

A comprehensive Flutter package for displaying country flags with support for multiple input formats and customizable styling options.

Features ✨ #

• 🌍 240+ Country Flags: Complete collection of world country flags
• 🔤 Multiple Input Formats: Support for ISO 2-letter codes, 3-letter codes, and country names
• 🎨 Customizable Styling: Various sizes, shapes, and border options
• 🔄 Smart Fallback: Graceful error handling with customizable fallback display
• 📱 Multiple Widgets: Different widgets for different use cases
• 🚀 High Performance: Optimized asset loading and caching

Installation 📦 #

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_country_flags: ^0.0.1

Then run:

flutter pub get

Usage 🚀 #

Basic Usage #

import 'package:flutter_country_flags/flutter_country_flags.dart';

// Basic flag display
FlutterCountryFlags(
  country: 'ir', // Iran flag
  width: 60,
  height: 40,
)

Different Input Formats #

// Using Country enum (Type-safe, recommended)
FlutterCountryFlags(country: Country.iran)

// ISO 2-letter code
FlutterCountryFlags(country: 'ir')

// ISO 3-letter code
FlutterCountryFlags(country: 'irn')

// Country name
FlutterCountryFlags(country: 'iran')

// Country name with spaces
FlutterCountryFlags(country: 'united states')

Widget Variants #

1. Standard Flag Widget

FlutterCountryFlags(
  country: Country.unitedStates, // Type-safe enum
  width: 60,
  height: 40,
  fit: BoxFit.cover,
  borderRadius: 8.0,
)

2. Simple Country Flag

CountryFlag(
  country: Country.unitedKingdom,
  size: 24, // Creates 24x16.8 flag (standard ratio)
)

3. Circular Flag

CircularCountryFlag(
  country: Country.germany,
  size: 50,
)

4. Flag with Country Name

CountryFlagWithName(
  country: Country.france,
  flagWidth: 50,
  flagHeight: 35,
  textStyle: TextStyle(fontSize: 12),
)

Advanced Customization #

FlutterCountryFlags(
  country: Country.japan, // Type-safe enum
  width: 80,
  height: 60,
  fit: BoxFit.cover,
  isCircular: true,
  borderRadius: 12.0,
  showCountryName: true,
  countryNameStyle: TextStyle(
    fontSize: 14,
    fontWeight: FontWeight.bold,
    color: Colors.blue,
  ),
  fallbackText: 'No Flag',
)

Supported Countries 🌎 #

The package supports 240+ countries and territories including:

• All UN member states
• Dependent territories
• Special regions (e.g., England, Scotland, Wales, Northern Ireland)
• Historical flags where applicable

Popular Country Codes #

Using Type-Safe Enum (Recommended)

Country.iran          // 🇮🇷 Iran
Country.unitedStates  // 🇺🇸 United States
Country.unitedKingdom // 🇬🇧 United Kingdom
Country.germany       // 🇩🇪 Germany
Country.france        // 🇫🇷 France
Country.japan         // 🇯🇵 Japan
Country.china         // 🇨🇳 China

// Special regions
Country.england       // 🏴󠁧󠁢󠁥󠁮󠁧󠁿 England
Country.scotland      // 🏴󠁧󠁢󠁳󠁣󠁴󠁿 Scotland
Country.wales         // 🏴󠁧󠁢󠁷󠁬󠁳󠁿 Wales
Country.europeanUnion // 🇪🇺 European Union

String Formats (Also Supported)

• 🇮🇷 Iran: 'ir', 'irn', 'iran'
• 🇺🇸 United States: 'us', 'usa', 'united states'
• 🇬🇧 United Kingdom: 'gb', 'gbr', 'united kingdom'
• 🇩🇪 Germany: 'de', 'deu', 'germany'
• 🇫🇷 France: 'fr', 'fra', 'france'
• 🇯🇵 Japan: 'jp', 'jpn', 'japan'
• 🇨🇳 China: 'cn', 'chn', 'china'

API Reference 📚 #

FlutterCountryFlags #

Country Enum API #

// Get country from code
Country? country = Country.fromCode('IR'); // Returns Country.iran

// Get country from name
Country? country = Country.fromName('iran'); // Returns Country.iran

// Get country properties
Country.iran.code;        // 'IR'
Country.iran.name;        // 'iran'
Country.iran.displayName; // 'Iran'

// Get all countries
List<String> codes = Country.allCodes;           // All ISO codes
List<String> names = Country.allNames;           // All internal names
List<String> displayNames = Country.allDisplayNames; // All display names

Legacy Utility Methods #

// Get country code from various inputs
String? code = CountryFlags.getCountryCode('iran'); // Returns 'IR'

// Get country name from code
String? name = CountryFlags.getCountryName('IR'); // Returns 'iran'

// Get all available country codes
List<String> codes = CountryFlags.getAllCountryCodes();

// Get all available country names
List<String> names = CountryFlags.getAllCountryNames();

Error Handling 🛡️ #

The package gracefully handles invalid inputs:

FlutterCountryFlags(
  country: 'invalid_code',
  fallbackText: 'Unknown',
  // Shows a placeholder with "Unknown" text
)

Examples 💡 #

Check out the /example folder for a comprehensive demo showing:

• Different input formats
• Various styling options
• Error handling
• Performance considerations