Country ISO #

A pure Dart package for converting ISO 3166-1 alpha-2 country codes to alpha-3 codes, numeric codes, and official country names. Perfect for displaying country flags in Flutter apps!

Features #

• 🏴 Flag Display Support: Get normalized alpha-2 codes for Flutter flag libraries
• Convert ISO 3166-1 alpha-2 codes (e.g., "ng", "us") to:
  • Alpha-3 codes (e.g., "NGA", "USA")
  • Numeric codes (e.g., "566", "840")
  • Official country names (e.g., "Nigeria", "United States of America")
• Case-insensitive input handling
• Returns null for invalid or unknown country codes
• Pure Dart implementation (no Flutter dependencies)
• Comprehensive dataset covering all ISO 3166-1 countries
• Lightweight and fast lookup performance

Flutter Flag Display Usage #

The primary use case for this package is displaying country flags in Flutter apps. Use the flagCode() method to get the normalized alpha-2 code:

import 'package:country_iso/country_iso.dart';

// Get flag code for any country input
String? flagCode = CountryISO.flagCode('NG'); // Returns 'ng'
String? flagCode2 = CountryISO.flagCode('us'); // Returns 'us'

// Use with popular Flutter flag packages:
if (flagCode != null) {
  // With country_flags package
  CountryFlag.fromCountryCode(flagCode);
  
  // With flag emoji
  // Convert to flag emoji using the alpha-2 code
}

// Validate country codes
bool isValid = CountryISO.isValid('ng'); // Returns true
bool isInvalid = CountryISO.isValid('xx'); // Returns false

Complete API Usage #

import 'package:country_iso/country_iso.dart';

void main() {
  // Get flag code (most common for Flutter apps)
  print(CountryISO.flagCode('NG')); // Output: ng
  print(CountryISO.flagCode('us')); // Output: us
  
  // Convert to alpha-3 code
  print(CountryISO.alpha3('ng')); // Output: NGA
  print(CountryISO.alpha3('US')); // Output: USA (case-insensitive)
  
  // Convert to numeric code
  print(CountryISO.numeric('ng')); // Output: 566
  print(CountryISO.numeric('us')); // Output: 840
  
  // Get country name
  print(CountryISO.name('ng')); // Output: Nigeria
  print(CountryISO.name('us')); // Output: United States of America
  
  // Validate country codes
  print(CountryISO.isValid('ng')); // Output: true
  print(CountryISO.isValid('xx')); // Output: false
  
  // Invalid codes return null
  print(CountryISO.flagCode('xx')); // Output: null
}

API Reference #

CountryISO.flagCode(String alpha2) ⭐ Most Used #

Validates and normalizes an ISO 3166-1 alpha-2 country code for flag display in Flutter apps.

• Parameters: alpha2 - The ISO 3166-1 alpha-2 country code (case-insensitive)
• Returns: The normalized lowercase alpha-2 code or null if invalid
• Perfect for: Flutter flag libraries and emoji systems

CountryISO.isValid(String alpha2) #

Checks if a given string is a valid ISO 3166-1 alpha-2 country code.

• Parameters: alpha2 - The ISO 3166-1 alpha-2 country code (case-insensitive)
• Returns: true if valid, false otherwise

CountryISO.alpha3(String alpha2) #

Converts an ISO 3166-1 alpha-2 country code to its alpha-3 equivalent.

• Parameters: alpha2 - The ISO 3166-1 alpha-2 country code (case-insensitive)
• Returns: The ISO alpha-3 code or null if invalid

CountryISO.numeric(String alpha2) #

Converts an ISO 3166-1 alpha-2 country code to its numeric equivalent.

• Parameters: alpha2 - The ISO 3166-1 alpha-2 country code (case-insensitive)
• Returns: The ISO numeric code as a string or null if invalid

CountryISO.name(String alpha2) #

Converts an ISO 3166-1 alpha-2 country code to its official country name.

• Parameters: alpha2 - The ISO 3166-1 alpha-2 country code (case-insensitive)
• Returns: The official country name or null if invalid

Supported Countries #

This package includes all 249 ISO 3166-1 countries and territories, including:

• All UN member states
• Dependent territories
• Special areas of geographical interest

Installation #

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

dependencies:
  country_iso: ^1.0.0

Then run:

dart pub get

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

License #

This project is licensed under the MIT License - see the LICENSE file for details.