Country Flags Widget #

A Flutter package for displaying country flags using images from flagcdn.com.

Features #

• Display country flags using ISO alpha-2 country codes
• No assets required - uses network images from flagcdn.com
• Customizable size, fit, border radius, and decoration
• Automatic country code normalization (uppercase to lowercase)
• Loading indicators and error handling
• Lightweight and easy to use

Installation #

Add this to your pubspec.yaml:

dependencies:
  country_flags_widget: ^1.0.0

Then run:

flutter pub get

Usage #

Basic Usage #

import 'package:country_flags_widget/country_flags.dart';

CountryFlag(
  countryCode: 'us',
)

CountryFlag(
  countryCode: 'vn',
  width: 100,
  height: 75,
)

Predefined Sizes #

CountryFlag.small(countryCode: 'us')
CountryFlag.medium(countryCode: 'vn')
CountryFlag.large(countryCode: 'fr')

Advanced Customization #

CountryFlag(
  countryCode: 'jp',
  width: 150,
  height: 100,
  fit: BoxFit.cover,
  borderRadius: BorderRadius.circular(8),
  decoration: BoxDecoration(
    border: Border.all(color: Colors.grey),
    boxShadow: [
      BoxShadow(
        color: Colors.black.withValues(alpha: 0.1),
        blurRadius: 4,
        offset: const Offset(0, 2),
      ),
    ],
  ),
)

Custom Loading and Error States #

CountryFlag(
  countryCode: 'de',
  placeholder: Container(
    color: Colors.grey[200],
    child: const Center(
      child: CircularProgressIndicator(),
    ),
  ),
  fallback: Container(
    color: Colors.grey[300],
    child: const Center(
      child: Icon(Icons.flag, color: Colors.grey),
    ),
  ),
)

Disable Loading Indicator #

CountryFlag(
  countryCode: 'it',
  showLoadingIndicator: false,
)

Custom Loading Indicator Color #

CountryFlag(
  countryCode: 'es',
  loadingIndicatorColor: Colors.blue,
)

Country Codes #

The package uses ISO alpha-2 country codes. Here are some examples:

• us - United States
• vn - Vietnam
• fr - France
• de - Germany
• jp - Japan
• gb - United Kingdom
• ca - Canada
• au - Australia
• br - Brazil
• in - India

Note: Country codes are automatically converted to lowercase, so both 'US' and 'us' will work.

API Reference #

CountryFlag #

A widget that displays a country flag using images from flagcdn.com.

Constructors

• CountryFlag() - Creates a country flag with custom parameters
• CountryFlag.small() - Creates a small flag (80x60)
• CountryFlag.medium() - Creates a medium flag (120x90)
• CountryFlag.large() - Creates a large flag (160x120)

Parameters

Example App #

Here's a complete example showing different ways to use the package:

import 'package:flutter/material.dart';
import 'package:country_flags_widget/country_flags.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Country Flags Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: const MyHomePage(),
    );
  }
}

class MyHomePage extends StatelessWidget {
  const MyHomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Country Flags Demo'),
      ),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            const Text(
              'Basic Flags:',
              style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold),
            ),
            const SizedBox(height: 16),
            Row(
              children: [
                CountryFlag.small(countryCode: 'us'),
                const SizedBox(width: 16),
                CountryFlag.small(countryCode: 'vn'),
                const SizedBox(width: 16),
                CountryFlag.small(countryCode: 'fr'),
                const SizedBox(width: 16),
                CountryFlag.small(countryCode: 'de'),
              ],
            ),
            const SizedBox(height: 32),
            const Text(
              'Different Sizes:',
              style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold),
            ),
            const SizedBox(height: 16),
            Row(
              children: [
                CountryFlag.small(countryCode: 'jp'),
                const SizedBox(width: 16),
                CountryFlag.medium(countryCode: 'jp'),
                const SizedBox(width: 16),
                CountryFlag.large(countryCode: 'jp'),
              ],
            ),
            const SizedBox(height: 32),
            const Text(
              'Custom Styling:',
              style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold),
            ),
            const SizedBox(height: 16),
            CountryFlag(
              countryCode: 'it',
              width: 120,
              height: 80,
              borderRadius: BorderRadius.circular(12),
              decoration: BoxDecoration(
                border: Border.all(color: Colors.grey),
                boxShadow: [
                  BoxShadow(
                    color: Colors.black.withValues(alpha: 0.1),
                    blurRadius: 4,
                    offset: const Offset(0, 2),
                  ),
                ],
              ),
            ),
          ],
        ),
      ),
    );
  }
}

License #

This package is licensed under the MIT License. See the LICENSE file for details.

Author #

Nguyen Thanh Bien (Nguyễn Thành Biên)

• Email: mortarcloud@gmail.com
• Website: https://algonest.io.vn

Copyright: Perpetual, unlimited use granted (Bản quyền sử dụng vĩnh viễn)

Contributing #

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

Issues #

If you find any issues or have feature requests, please create an issue.