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.