Countrify

https://pub.dev/packages/countrify
Admin
Countrify is a comprehensive Flutter package providing beautiful, customizable country, state, and...
Tokens:28,460
Snippets:267
Trust Score:9.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Clone Repository and Install Dependencies

Source: https://pub.dev/packages/countrify

Instructions for cloning the Countrify repository and setting up the project locally. Ensure you have Flutter installed.

```bash
git clone https://github.com/Arhamss/countrify.git
cd countrify
flutter pub get
```

--------------------------------

### Run Example App and Tests

Source: https://pub.dev/packages/countrify

Commands to run the example application and execute tests for the Countrify package. This helps in verifying the package's functionality.

```bash
cd example && flutter run
```

```bash
flutter test
```

```bash
flutter analyze
```

--------------------------------

### Run flutter pub get

Source: https://pub.dev/packages/countrify

After adding the dependency, run this command to fetch the package.

```bash
flutter pub get

```

--------------------------------

### CountrySearchBar Example

Source: https://pub.dev/packages/countrify/example

Integrates a search bar for countries with a callback for search queries. Requires the CountrySearchBar widget.

```dart
_buildBlockLabel('CountrySearchBar'),
        const SizedBox(height: 10),
        _ShowcaseCard(
          child: CountrySearchBar(
            hintText: 'Search countries...', 
            onChanged: (query) => debugPrint('Search: $query'),
          ),
        )
```

--------------------------------

### Countrify Flutter App Entry Point

Source: https://pub.dev/packages/countrify/example

Sets up the main MaterialApp for the Countrify example app, including theme configuration and navigation.

```dart
import 'package:countrify/countrify.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

void main() => runApp(const CountrifyExampleApp());

// ═══════════════════════════════════════════════════════════════════════════
// Design Tokens
// ═══════════════════════════════════════════════════════════════════════════

class _C {
  _C._();
  // Primary palette
  static const indigo = Color(0xFF4F46E5);
  static const indigoSubtle = Color(0xFFEEF2FF);

  // Accent
  static const teal = Color(0xFF0D9488);
  static const tealSubtle = Color(0xFFCCFBF1);

  // Neutrals
  static const slate900 = Color(0xFF0F172A);
  static const slate700 = Color(0xFF334155);
  static const slate500 = Color(0xFF64748B);
  static const slate400 = Color(0xFF94A3B8);
  static const slate200 = Color(0xFFE2E8F0);
  static const slate100 = Color(0xFFF1F5F9);
  static const slate50 = Color(0xFFF8FAFC);
  static const white = Colors.white;

  // Surfaces
  static const cardBg = Colors.white;
  static const scaffoldBg = Color(0xFFF8FAFC);
}

// ═══════════════════════════════════════════════════════════════════════════
// App Root
// ═══════════════════════════════════════════════════════════════════════════

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Countrify',
      debugShowCheckedModeBanner: false,
      theme: ThemeData(
        colorSchemeSeed: _C.indigo,
        useMaterial3: true,
        scaffoldBackgroundColor: _C.scaffoldBg,
        appBarTheme: const AppBarTheme(
          systemOverlayStyle: SystemUiOverlayStyle.dark,
        ),
      ),
      home: const HomePage(),
    );
  }
}

// ═══════════════════════════════════════════════════════════════════════════
// Home — Tab Navigation
// ═══════════════════════════════════════════════════════════════════════════

class HomePage extends StatefulWidget {
  const HomePage({super.key});

  @override
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> with TickerProviderStateMixin {
  late final TabController _tabController;

  static const _tabs = [
    _TabItem(icon: Icons.phone_outlined, label: 'Phone'),
    _TabItem(icon: Icons.public_outlined, label: 'Country'),
    _TabItem(icon: Icons.location_city_outlined, label: 'Address'),
    _TabItem(icon: Icons.palette_outlined, label: 'Themes'),
    _TabItem(icon: Icons.translate_outlined, label: 'i18n'),
    _TabItem(icon: Icons.widgets_outlined, label: 'Blocks'),
  ];

  @override
  void initState() {
    super.initState();
    _tabController = TabController(length: _tabs.length, vsync: this);
    _tabController.addListener(() => setState(() {}));
  }

  @override
  void dispose() {
    _tabController.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: () => FocusScope.of(context).unfocus(),
      child: Scaffold(
      backgroundColor: _C.scaffoldBg,
      body: NestedScrollView(
        headerSliverBuilder: (context, innerBoxIsScrolled) => [
          SliverAppBar(
            expandedHeight: 120,
            floating: true,
            pinned: true,
            elevation: 0,
            scrolledUnderElevation: 0.5,
            backgroundColor: _C.white,
            surfaceTintColor: Colors.transparent,
            flexibleSpace: FlexibleSpaceBar(
              titlePadding:
                  const EdgeInsets.only(left: 24, bottom: 56),
              title: Row(
                mainAxisSize: MainAxisSize.min,
                children: [
                  Container(
                    width: 28,
                    height: 28,
                    decoration: BoxDecoration(
                      gradient: const LinearGradient(
                        colors: [_C.indigo, _C.teal],
                        begin: Alignment.topLeft,
                        end: Alignment.bottomRight,
                      ),
                      borderRadius: BorderRadius.circular(8),
                    ),
                    child: const Icon(
                      Icons.public,
                      color: Colors.white,
                      size: 16,
                    ),
                  ),
                  const SizedBox(width: 10),
                  const Text(
                    'Countrify',
                    style: TextStyle(
                      color: _C.slate900,
                      fontWeight: FontWeight.w700,
                      fontSize: 20,
                      letterSpacing: -0.5,
                    ),
                  ),
                ],
              ),
            ),
          )
        ],
        body: TabBarView(
          controller: _tabController,
          children: const [
            // TODO: implement Phone tab
            Center(child: Text('Phone')),
            // TODO: implement Country tab
            Center(child: Text('Country')),
            // TODO: implement Address tab
            Center(child: Text('Address')),
            // TODO: implement Themes tab
            Center(child: Text('Themes')),
            // TODO: implement i18n tab
            Center(child: Text('i18n')),
            // TODO: implement Blocks tab
            Center(child: Text('Blocks')),
          ],
        ),
      ),
      bottomNavigationBar: BottomAppBar(
        height: 72,
        color: _C.white,
        elevation: 0,
        shape: const CircularNotchedRectangle(),
        child: TabBar(
          controller: _tabController,
          indicatorColor: _C.indigo,
          labelColor: _C.indigo,
          unselectedLabelColor: _C.slate400,
          tabs: _tabs
              .map((_TabItem tab) => Tab(
                    icon: Icon(tab.icon),
                    text: tab.label,
                  ))
              .toList(),
        ),
      ),
      floatingActionButtonLocation: FloatingActionButtonLocation.centerDocked,
      floatingActionButton: FloatingActionButton(
        onPressed: () {},
        backgroundColor: _C.teal,
        child: const Icon(Icons.add),
      ),
    ),
    );
  }
}

class _TabItem {
  const _TabItem({required this.icon, required this.label});
  final IconData icon;
  final String label;
}

```

--------------------------------

### Country Dropdown Field Example

Source: https://pub.dev/packages/countrify/example

Demonstrates the usage of the CountryDropdownField for selecting a country. Includes styling and handling country selection changes.

```dart
CountryDropdownField(
                key: ValueKey(_pickerMode),
                pickerMode: _pickerMode,
                style: CountrifyFieldStyle.defaultStyle().copyWith(
                  labelText: 'Select a country',
                  fillColor: _C.slate50,
                  focusedFillColor: _C.indigoSubtle,
                  cursorColor: _C.indigo,
                  enabledBorder: OutlineInputBorder(
                    borderRadius: BorderRadius.circular(12),
                    borderSide: const BorderSide(color: _C.slate200),
                  ),
                  focusedBorder: OutlineInputBorder(
                    borderRadius: BorderRadius.circular(12),
                    borderSide:
                        const BorderSide(color: _C.indigo, width: 1.5),
                  ),
                ),
                onChanged: (country) {
                  setState(() {
                    _selectedCountry = country.name;
                    _selectedFlag = country.flagEmoji;
                  });
                },
              )
```

--------------------------------

### PhoneCodePicker Example

Source: https://pub.dev/packages/countrify/example

Implements a phone code picker with an initial country code and a callback for country code changes. Requires the PhoneCodePicker widget.

```dart
// Phone Code Picker
        _buildBlockLabel('PhoneCodePicker'),
        const SizedBox(height: 10),
        _ShowcaseCard(
          child: PhoneCodePicker(
            initialCountryCode: CountryCode.us,
            onChanged: (country) {
              debugPrint(
                  'Code: +${country.callingCodes.first}');
            },
          ),
        )
```

--------------------------------

### CountryListTile Example

Source: https://pub.dev/packages/countrify/example

Displays a list of countries using CountryListTile, allowing selection. Requires a list of country objects and state management for selection.

```dart
_buildBlockLabel('CountryListTile'),
        const SizedBox(height: 10),
        _ShowcaseCard(
          padding: const EdgeInsets.symmetric(
              horizontal: 8, vertical: 8),
          child: Column(
            children: [us, gb, jp, br].map((c) {
              return CountryListTile(
                country: c,
                isSelected:
                    _selectedCountry.alpha2Code == c.alpha2Code,
                onTap: (country) =>
                    setState(() => _selectedCountry = country),
              );
            }).toList(),
          ),
        )
```

--------------------------------

### Quick Start: Basic Phone Number Input

Source: https://pub.dev/packages/countrify

Use PhoneNumberField for a simple phone number input with a default country code.

```dart
PhoneNumberField(
  initialCountryCode: CountryCode.us,
  onChanged: (phoneNumber, country) {
    print('Full number: +${country.callingCodes.first}$phoneNumber');
  },
)

```

--------------------------------

### StatePicker Search Example

Source: https://pub.dev/packages/countrify

Demonstrates advanced search configurations for StatePicker, including initial search text, debounce delay, accent-insensitive matching, autofocus, and custom matchers.

```dart
StatePicker(
  countryIso2: 'BR',
  config: const GeoPickerConfig(
    initialSearchText: 'sao',
    searchDebounce: Duration(milliseconds: 200),
    accentInsensitiveSearch: true,       // "sao paulo" matches "São Paulo"
    autofocusSearch: true,
  ),
  onSearchChanged: (q) => print('typed: $q'),
  onResultsChanged: (results) => print('${results.length} match'),
  customMatcher: (state, query) =>
      state.name.toLowerCase().contains(query) ||
      (state.iso2?.toLowerCase() == query),
  onStateSelected: (s) => print(s.name),
)
```

--------------------------------

### CountryPicker with Dark Theme

Source: https://pub.dev/packages/countrify

Example of applying a dark theme to the CountryPicker widget. Includes options to show phone code and enable search.

```dart
CountryPicker(
  onCountrySelected: (country) { },
  theme: CountryPickerTheme.darkTheme(),
  showPhoneCode: true,
  searchEnabled: true,
)
```

--------------------------------

### Countrify Dependency in pubspec.yaml

Source: https://pub.dev/packages/countrify/install

This is an example of how the countrify dependency will appear in your pubspec.yaml file after running `flutter pub add countrify`.

```yaml
dependencies:
  countrify: ^2.5.0
```

--------------------------------

### Get Metadata Collections

Source: https://pub.dev/packages/countrify

Retrieve comprehensive lists of all available regions, subregions, currencies, languages, and timezones recognized by the package using various CountryUtils methods.

```dart
final regions = CountryUtils.getAllRegions();         // ["Africa", "Americas", ...]
final subregions = CountryUtils.getAllSubregions();   // ["Caribbean", "Central Asia", ...]
final currencies = CountryUtils.getAllCurrencies();
final languages = CountryUtils.getAllLanguages();
final timezones = CountryUtils.getAllTimezones();

```

--------------------------------

### Fetch Countries by Language Code

Source: https://pub.dev/packages/countrify

Get a list of countries where a specific language is spoken, using its ISO 639-1 code with CountryUtils.getCountriesByLanguageCode().

```dart
// Get by language
final englishSpeaking = CountryUtils.getCountriesByLanguageCode('en');

```

--------------------------------

### Fetch Country by ISO Code

Source: https://pub.dev/packages/countrify

Get specific country data by its Alpha-2, Alpha-3, or Numeric ISO codes using CountryUtils. Requires the correct code format for accurate retrieval.

```dart
// Get by ISO code
final usa = CountryUtils.getCountryByAlpha2Code('US');
final canada = CountryUtils.getCountryByAlpha3Code('CAN');
final germany = CountryUtils.getCountryByNumericCode('276');

```

--------------------------------

### Programmatic Country Name Access

Source: https://pub.dev/packages/countrify

Use `CountryUtils` to get localized country names and translations programmatically outside of widgets.

```APIDOC
## Programmatic Access

Use `CountryUtils` to get localized names in code (outside of widgets):

```dart
final usa = CountryUtils.getCountryByAlpha2Code('US')!;

CountryUtils.getCountryNameInLanguage(usa, 'de'); // "Vereinigte Staaten"
CountryUtils.getCountryNameInLanguage(usa, 'fr'); // "États-Unis"
CountryUtils.getCountryNameInLanguage(usa, 'ja'); // "アメリカ合衆国"
CountryUtils.getCountryNameInLanguage(usa, 'ar'); // "الولايات المتحدة"
CountryUtils.getCountryNameInLanguage(usa, 'zh'); // "美国"
CountryUtils.getCountryNameInLanguage(usa, 'hi'); // "संयुक्त राज्य"
```

The method checks the country's `nameTranslations` map first (for user-provided overrides), then falls back to the built-in CLDR data, and finally returns the English name.
```

```APIDOC
### Get All Translations for a Country

```dart
final allNames = CountryUtils.getCountryNamesInAllLanguages(usa);
// Returns a Map<String, String> with 130+ entries:
// {"af": "Verenigde State van Amerika", "ar": "الولايات المتحدة", "de": "Vereinigte Staaten", ...}
```
```

```APIDOC
### List Supported Locales

```dart
final locales = CountryUtils.getSupportedLocales();
// ["af", "ak", "am", "ar", "as", "az", "be", "bg", ..., "zh", "zu"]
// 132 locale codes
```
```

--------------------------------

### Cascading Address Field Example

Source: https://pub.dev/packages/countrify/example

Shows how to use the CountryStateCityField for a cascading selection of country, state, and city. Includes initial country code and field styling.

```dart
CountryStateCityField(
            initialCountryCode: CountryCode.us,
            spacing: 14,
            fieldStyle: CountrifyFieldStyle.defaultStyle().copyWith(
              fillColor: _C.slate50,
              focusedFillColor: _C.indigoSubtle,
              cursorColor: _C.indigo,
              enabledBorder: OutlineInputBorder(
                borderRadius: BorderRadius.circular(12),
                borderSide: const BorderSide(color: _C.slate200),
              ),
              focusedBorder: OutlineInputBorder(
                borderRadius: BorderRadius.circular(12),
                borderSide:
                    const BorderSide(color: _C.indigo, width: 1.5),
              ),
            ),
            onChanged: (sel) => setState(() => _selection = sel),
          )
```

--------------------------------

### Get Supported Locales via CountryNameL10n

Source: https://pub.dev/packages/countrify

Access the list of supported locale codes directly from `CountryNameL10n.supportedLocales`. This provides the same information as `CountryUtils.getSupportedLocales` but through a different interface.

```dart
import 'package:countrify/countrify.dart';

// Check supported locales
final locales = CountryNameL10n.supportedLocales; // 132 entries

```

--------------------------------

### Custom Filter Bar Builder

Source: https://pub.dev/packages/countrify

Provide a custom filter interface using customFilterBuilder. This example demonstrates using FilterChips to allow users to select regions.

```dart
customFilterBuilder: (context, filter, onChanged) {
  return Wrap(
    children: ['Europe', 'Asia', 'Africa'].map((region) {
      return FilterChip(
        label: Text(region),
        selected: filter.regions.contains(region),
        onSelected: (selected) {
          final regions = selected
              ? [...filter.regions, region]
              : filter.regions.where((r) => r != region).toList();
          onChanged(filter.copyWith(regions: regions));
        },
      );
    }).toList(),
  );
}

```

--------------------------------

### Get List of Supported Locales

Source: https://pub.dev/packages/countrify

Obtain a list of all supported locale codes by the Countrify package using `CountryUtils.getSupportedLocales`. This provides a comprehensive list of languages for which country names are available.

```dart
final locales = CountryUtils.getSupportedLocales();
// ["af", "ak", "am", "ar", "as", "az", "be", "bg", ..., "zh", "zu"]
// 132 locale codes

```

--------------------------------

### Get World Statistics

Source: https://pub.dev/packages/countrify

Access global statistics like total world population and area, or find the most populous and largest countries using CountryUtils. Includes formatting utilities for these values.

```dart
final totalPopulation = CountryUtils.getTotalWorldPopulation();
final totalArea = CountryUtils.getTotalWorldArea();

final mostPopulous = CountryUtils.getMostPopulousCountry();
final largest = CountryUtils.getLargestCountry();
final smallest = CountryUtils.getSmallestCountry();

// Formatted output
print(CountryUtils.formatPopulation(totalPopulation)); // "7,794,798,739"
print(CountryUtils.formatArea(totalArea));              // "148,940,000.00"

```

--------------------------------

### Phone Number Input with PhoneNumberField

Source: https://pub.dev/packages/countrify

Example of using PhoneNumberField for phone number input. Includes styling, input formatters for digits only and length limiting, and callbacks for number and country changes.

```dart
PhoneNumberField(
  style: const CountrifyFieldStyle(
    hintText: 'Enter phone number',
    labelText: 'Phone',
  ),
  theme: CountryPickerTheme.defaultTheme(),
  inputFormatters: [
    FilteringTextInputFormatter.digitsOnly,
    LengthLimitingTextInputFormatter(15),
  ],
  onChanged: (phoneNumber, country) {
    print('Full number: +${country.callingCodes.first}$phoneNumber');
  },
  onCountryChanged: (country) {
    print('Country changed: ${country.name}');
  },
)
```

--------------------------------

### CountryUtils - Filtered Collections

Source: https://pub.dev/packages/countrify

Utilities to get specific filtered collections of countries.

```APIDOC
## CountryUtils - Filtered Collections

### Description
Provides methods to retrieve specific filtered lists of countries.

### Methods
- **getIndependentCountries()**: Returns a list of independent countries.
- **getUnMemberCountries()**: Returns a list of UN member countries.

### Examples
```dart
final independent = CountryUtils.getIndependentCountries();
final unMembers = CountryUtils.getUnMemberCountries();
```
```

--------------------------------

### Get Bordering Countries

Source: https://pub.dev/packages/countrify

Find countries that share a border with a specified country using its Alpha-2 code with CountryUtils.getBorderCountries().

```dart
// Get bordering countries
final neighbors = CountryUtils.getBorderCountries('USA');

```

--------------------------------

### Helper Widget: _buildBlockLabel

Source: https://pub.dev/packages/countrify/example

A helper widget to create styled labels for UI blocks. Uses a Container with specific decoration and text styling.

```dart
static Widget _buildBlockLabel(String text) {
    return Row(
      children: [
        Container(
          padding:
              const EdgeInsets.symmetric(horizontal: 10, vertical: 5),
          decoration: BoxDecoration(
            color: _C.indigoSubtle,
            borderRadius: BorderRadius.circular(6),
          ),
          child: Text(
            text,
            style: const TextStyle(
              fontSize: 12,
              fontWeight: FontWeight.w700,
              color: _C.indigo,
              letterSpacing: 0.3,
              fontFamily: 'monospace',
            ),
          ),
        ),
      ],
    );
  }
```

--------------------------------

### Build Style Label Widget

Source: https://pub.dev/packages/countrify/example

A helper widget to create a styled label with a colored dot and text, used for section titles.

```dart
Widget _buildStyleLabel(String text) {
    return Row(
      children: [
        Container(
          width: 6,
          height: 6,
          decoration: BoxDecoration(
            color: _C.teal,
            borderRadius: BorderRadius.circular(3),
          ),
        ),
        const SizedBox(width: 8),
        Text(
          text,
          style: const TextStyle(
            fontSize: 12,
            fontWeight: FontWeight.w600,
            color: _C.slate500,
            letterSpacing: 0.5,
          ),
        ),
      ],
    );
  }
```

--------------------------------

### Create Custom Country Picker Theme

Source: https://pub.dev/packages/countrify

Use `CountryPickerTheme.custom()` for initial theming and `copyWith()` to modify specific properties. This allows for quick theme creation or fine-grained adjustments to visual elements like border radii and text styles.

```dart
final customTheme = CountryPickerTheme.custom(
  primaryColor: Colors.deepPurple,
  backgroundColor: Colors.white,
  isDark: false,
).copyWith(
  countryItemBorderRadius: BorderRadius.circular(16),
  searchBarBorderRadius: BorderRadius.circular(24),
  headerTextStyle: const TextStyle(
    fontSize: 24,
    fontWeight: FontWeight.bold,
    letterSpacing: 1.2,
  ),
);
```

--------------------------------

### Import Countrify Package in Dart Code

Source: https://pub.dev/packages/countrify/install

Import the countrify library into your Dart files to start using its country picker functionalities.

```dart
import 'package:countrify/countrify.dart';
```

--------------------------------

### Define Full Country Picker Theme Properties

Source: https://pub.dev/packages/countrify

Customize every visual aspect of the country picker using the `CountryPickerTheme` constructor. This includes colors, text styles, border radii, icons, and animation durations for various components like the header, search bar, country items, and filter chips.

```dart
const theme = CountryPickerTheme(
  // ─── Background ──────────────────────────────────
  backgroundColor: Colors.white,
  headerColor: Color(0xFFF5F5F5),

  // ─── Header ──────────────────────────────────────
  headerTextStyle: TextStyle(fontSize: 18, fontWeight: FontWeight.w600),
  headerIconColor: Colors.black54,

  // ─── Search Bar ──────────────────────────────────
  searchBarColor: Color(0xFFF8F9FA),
  searchTextStyle: TextStyle(fontSize: 16),
  searchHintStyle: TextStyle(fontSize: 16, color: Colors.black54),
  searchIconColor: Colors.black54,
  searchBarBorderColor: Color(0xFFE0E0E0),
  searchBarBorderRadius: BorderRadius.all(Radius.circular(12)),
  searchHintText: 'Search countries...', 
  searchCursorColor: Colors.blue,
  searchFocusedBorderColor: Colors.blue,
  searchInputDecoration: null,         // Full InputDecoration override

  // ─── Country Items ───────────────────────────────
  countryItemBackgroundColor: Colors.white,
  countryItemSelectedColor: Color(0xFFE3F2FD),
  countryItemSelectedBorderColor: Color(0xFF2196F3),
  countryItemSelectedIconColor: Color(0xFF2196F3),
  countryItemBorderRadius: BorderRadius.all(Radius.circular(8)),
  countryNameTextStyle: TextStyle(fontSize: 16, fontWeight: FontWeight.w500),
  countrySubtitleTextStyle: TextStyle(fontSize: 14, color: Colors.grey),
  compactCountryNameTextStyle: TextStyle(fontSize: 13, color: Colors.black54),
  compactDialCodeTextStyle: TextStyle(fontSize: 14, fontWeight: FontWeight.w600),
  readOnlyHintTextStyle: TextStyle(fontSize: 14, color: Colors.black54),
  flagEmojiTextStyle: TextStyle(fontSize: 16),
  appBarTitleTextStyle: TextStyle(fontSize: 20, fontWeight: FontWeight.w600),
  dialogOptionTextStyle: TextStyle(fontSize: 14),
  dialogActionTextStyle: TextStyle(fontSize: 14, fontWeight: FontWeight.w600),

  // ─── Filter Chips ────────────────────────────────
  filterBackgroundColor: Color(0xFFF0F0F0),
  filterSelectedColor: Color(0xFF2196F3),
  filterTextColor: Colors.black87,
  filterSelectedTextColor: Colors.white,
  filterCheckmarkColor: Colors.white,
  filterIconColor: Colors.black54,

  // ─── Borders & Elevation ─────────────────────────
  borderColor: Color(0xFFE0E0E0),
  borderRadius: BorderRadius.all(Radius.circular(20)),
  elevation: 8.0,
  shadowColor: Color(0x1A000000),

  // ─── Scrollbar ───────────────────────────────────
  scrollbarThickness: 6.0,
  scrollbarRadius: BorderRadius.all(Radius.circular(3)),

  // ─── Dropdown-Specific ───────────────────────────
  dropdownMenuBackgroundColor: Colors.white,
  dropdownMenuElevation: 8,
  dropdownMenuBorderRadius: BorderRadius.all(Radius.circular(12)),
  dropdownMenuBorderColor: Colors.grey,
  dropdownMenuBorderWidth: 1,

  // ─── Customizable Icons ──────────────────────────
  closeIcon: CountrifyIcons.x,
  searchIcon: CountrifyIcons.search,
  clearIcon: CountrifyIcons.circleX,
  selectedIcon: CountrifyIcons.circleCheckBig,
  filterIcon: CountrifyIcons.listFilter,
  dropdownIcon: CountrifyIcons.chevronDown,
  emptyStateIcon: CountrifyIcons.searchX,
  defaultCountryIcon: CountrifyIcons.globe,

  // ─── Behavior ────────────────────────────────────
  animationDuration: Duration(milliseconds: 300),
  hapticFeedback: true,
);
```

--------------------------------

### Theming Tab Widget

Source: https://pub.dev/packages/countrify/example

A StatefulWidget that allows users to select and preview different themes for the Countrify package. It demonstrates how to apply default, dark, Material 3, and custom themes.

```dart
class ThemingTab extends StatefulWidget {
  const ThemingTab({super.key});

  @override
  State<ThemingTab> createState() => _ThemingTabState();
}

class _ThemingTabState extends State<ThemingTab> {
  int _selectedTheme = 0;

  static const _themes = [
    _ThemeOption(
      label: 'Default',
      icon: Icons.light_mode_outlined,
      desc: 'Clean light theme',
      color: Color(0xFF2196F3),
      bgColor: Colors.white,
    ),
    _ThemeOption(
      label: 'Dark',
      icon: Icons.dark_mode_outlined,
      desc: 'For dark interfaces',
      color: Color(0xFF64B5F6),
      bgColor: Color(0xFF1E1E1E),
    ),
    _ThemeOption(
      label: 'Material 3',
      icon: Icons.auto_awesome_outlined,
      desc: 'Google M3 tokens',
      color: Color(0xFF6750A4),
      bgColor: Color(0xFFFFFBFE),
    ),
    _ThemeOption(
      label: 'Custom',
      icon: Icons.tune_outlined,
      desc: 'Teal accent',
      color: _C.teal,
      bgColor: Colors.white,
    ),
  ];

  CountryPickerTheme get _currentTheme {
    switch (_selectedTheme) {
      case 1:
        return CountryPickerTheme.darkTheme();
      case 2:
        return CountryPickerTheme.material3Theme();
      case 3:
        return CountryPickerTheme.custom(primaryColor: _C.teal);
      default:
        return CountryPickerTheme.defaultTheme();
    }
  }

  CountrifyFieldStyle get _currentFieldStyle {
    if (_selectedTheme == 1) {
      return CountrifyFieldStyle.darkStyle()
          .copyWith(hintText: 'Themed phone field');
    }
    return CountrifyFieldStyle.defaultStyle().copyWith(
      hintText: 'Themed phone field',
      fillColor: _themes[_selectedTheme].bgColor,
      focusedFillColor: _themes[_selectedTheme]
          .color
          .withValues(alpha: 0.08),
      cursorColor: _themes[_selectedTheme].color,
    );
  }
}
```

--------------------------------

### Regenerate Bundled Dataset

Source: https://pub.dev/packages/countrify

Use the dart run command to regenerate vendored assets from the upstream dataset. Specify a ref for a specific tag or an input path for offline sources.

```bash
dart run tool/sync_geo_data.dart                     # latest master
dart run tool/sync_geo_data.dart --ref v2.6          # specific tag
dart run tool/sync_geo_data.dart --input path.json   # offline source
```

--------------------------------

### Theme Gallery UI in Flutter

Source: https://pub.dev/packages/countrify/example

Builds a scrollable gallery of theme cards using GridView. Each card displays theme information and allows selection, updating the UI state.

```dart
return ListView(
      padding: const EdgeInsets.fromLTRB(20, 28, 20, 40),
      children: [
        const _SectionHeader(
          icon: Icons.palette_outlined,
          title: 'Theme Gallery',
          subtitle:
              'Pre-built themes and custom theme support. Tap to preview.',
        ),
        // Theme cards grid
        GridView.count(
          crossAxisCount: 2,
          mainAxisSpacing: 10,
          crossAxisSpacing: 10,
          childAspectRatio: 1.55,
          shrinkWrap: true,
          physics: const NeverScrollableScrollPhysics(),
          children: List.generate(_themes.length, (i) {
            final t = _themes[i];
            final isSelected = _selectedTheme == i;
            return GestureDetector(
              onTap: () => setState(() => _selectedTheme = i),
              child: AnimatedContainer(
                duration: const Duration(milliseconds: 200),
                padding: const EdgeInsets.all(14),
                decoration: BoxDecoration(
                  color: _C.white,
                  borderRadius: BorderRadius.circular(14),
                  border: Border.all(
                    color: isSelected ? t.color : _C.slate200,
                    width: isSelected ? 2 : 1,
                  ),
                  boxShadow: isSelected
                      ? [
                          BoxShadow(
                            color: t.color.withValues(alpha: 0.15),
                            blurRadius: 12,
                            offset: const Offset(0, 4),
                          ),
                        ]
                      : null,
                ),
                child: Column(
                  crossAxisAlignment: CrossAxisAlignment.start,
                  children: [
                    Row(
                      children: [
                        Container(
                          padding: const EdgeInsets.all(6),
                          decoration: BoxDecoration(
                            color: t.color.withValues(alpha: 0.1),
                            borderRadius: BorderRadius.circular(8),
                          ),
                          child: Icon(t.icon,
                              size: 16, color: t.color),
                        ),
                        const Spacer(),
                        if (isSelected)
                          Container(
                            width: 20,
                            height: 20,
                            decoration: BoxDecoration(
                              color: t.color,
                              shape: BoxShape.circle,
                            ),
                            child: const Icon(Icons.check,
                                size: 12, color: Colors.white),
                          ),
                      ],
                    ),
                    const Spacer(),
                    Text(
                      t.label,
                      style: const TextStyle(
                        fontSize: 14,
                        fontWeight: FontWeight.w700,
                        color: _C.slate900,
                      ),
                    ),
                    Text(
                      t.desc,
                      style: const TextStyle(
                        fontSize: 11,
                        color: _C.slate400,
                      ),
                    ),
                  ],
                ),
              ),
            );
          }),
        ),
        const SizedBox(height: 20),
        // Preview
        AnimatedContainer(
          duration: const Duration(milliseconds: 300),
          padding: const EdgeInsets.all(20),
          decoration: BoxDecoration(
            color: _selectedTheme == 1
                ? const Color(0xFF1A1A2E)
                : _C.white,
            borderRadius: BorderRadius.circular(16),
            border: Border.all(
              color: _selectedTheme == 1
                  ? const Color(0xFF2D2D4A)
                  : _C.slate200.withValues(alpha: 0.8),
            ),
            boxShadow: [
              BoxShadow(
                color: theme.color.withValues(alpha: 0.06),
                blurRadius: 16,
                offset: const Offset(0, 4),
              ),
            ],
          ),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              Row(
                children: [
                  Container(
                    width: 8,
                    height: 8,
                    decoration: BoxDecoration(
                      color: theme.color,
                      shape: BoxShape.circle,
                    ),
                  ),
                ],
              ),
            ],
          ),
        ),
      ],
    );
  }
}
```

--------------------------------

### Get Filtered Country Collections

Source: https://pub.dev/packages/countrify

Retrieve specific subsets of countries, such as only independent nations or UN member states, using CountryUtils.getIndependentCountries() and CountryUtils.getUnMemberCountries().

```dart
final independent = CountryUtils.getIndependentCountries();
final unMembers = CountryUtils.getUnMemberCountries();

```

--------------------------------

### Build Metadata Widget

Source: https://pub.dev/packages/countrify/example

Builds a widget to display metadata, conditionally showing an icon and label before the value. Handles overflow with ellipsis.

```dart
Widget build(BuildContext context) {
    return Row(
      children: [
        if (icon != null) ...[
          Icon(icon, size: 16, color: _C.slate400),
          const SizedBox(width: 8),
        ],
        Text(
          label,
          style: const TextStyle(
            fontSize: 13,
            color: _C.slate500,
            fontWeight: FontWeight.w500,
          ),
        ),
        const SizedBox(width: 8),
        Flexible(
          child: Text(
            value,
            style: const TextStyle(
              fontSize: 14,
              color: _C.slate900,
              fontWeight: FontWeight.w600,
            ),
            overflow: TextOverflow.ellipsis,
          ),
        ),
      ],
    );
  }
}
```

--------------------------------

### CountryUtils - Fetching Countries

Source: https://pub.dev/packages/countrify

Utilities to fetch country data programmatically without displaying a UI.

```APIDOC
## CountryUtils - Fetching Countries

### Description
Use `CountryUtils` to access country data programmatically.

### Methods
- **getAllCountries()**: Returns a list of all countries.
- **getCountryByAlpha2Code(String code)**: Returns a country by its 2-letter ISO code.
- **getCountryByAlpha3Code(String code)**: Returns a country by its 3-letter ISO code.
- **getCountryByNumericCode(String code)**: Returns a country by its 3-digit numeric code.
- **searchCountries(String query)**: Searches for countries by name (case-insensitive).
- **getCountriesByRegion(String region)**: Returns countries belonging to a specific region.
- **getCountriesBySubregion(String subregion)**: Returns countries belonging to a specific subregion.
- **getCountriesByCallingCode(String code)**: Returns countries by their international calling code.
- **getCountriesByCurrencyCode(String code)**: Returns countries that use a specific currency.
- **getCountriesByLanguageCode(String code)**: Returns countries where a specific language is spoken.
- **getBorderCountries(String countryCode)**: Returns countries that share a border with the specified country.

### Examples
```dart
// Get all countries
final countries = CountryUtils.getAllCountries();

// Get by ISO code
final usa = CountryUtils.getCountryByAlpha2Code('US');
final canada = CountryUtils.getCountryByAlpha3Code('CAN');
final germany = CountryUtils.getCountryByNumericCode('276');

// Search by name
final results = CountryUtils.searchCountries('united');

// Get by region
final european = CountryUtils.getCountriesByRegion('Europe');

// Get by calling code
final countriesWith1 = CountryUtils.getCountriesByCallingCode('+1');

// Get by currency
final euroCountries = CountryUtils.getCountriesByCurrencyCode('EUR');

// Get by language
final englishSpeaking = CountryUtils.getCountriesByLanguageCode('en');

// Get bordering countries
final neighbors = CountryUtils.getBorderCountries('USA');
```
```

--------------------------------

### Build Outline Style PhoneNumberField

Source: https://pub.dev/packages/countrify/example

Shows how to implement a PhoneNumberField using the outline style, allowing for custom border and focused border colors.

```dart
PhoneNumberField(
                initialCountryCode: CountryCode.jp,
                style: CountrifyFieldStyle.outlineStyle(
                  borderColor: _C.slate200,
                  focusedBorderColor: _C.indigo,
                ).copyWith(
                  hintText: 'Outline variant',
                  cursorColor: _C.indigo,
                ),
                onChanged: (_, __) {},
              )
```

--------------------------------

### Troubleshooting Flag Image Loading

Source: https://pub.dev/packages/countrify

For reliable flag loading, use the `CountryFlag` widget. If using `Image.asset` directly, always include the `package` parameter to avoid loading issues.

```dart
// Recommended:
CountryFlag(
  country: country,
  size: const Size(32, 24),
)

// Or with Image.asset directly:
Image.asset(
  country.flagImagePath,
  package: 'countrify',  // Don't forget this!
  width: 32,
  height: 24,
)
```

--------------------------------

### Build Filled Style PhoneNumberField

Source: https://pub.dev/packages/countrify/example

Demonstrates how to create a PhoneNumberField with a filled style, customizing border colors and hint text.

```dart
PhoneNumberField(
                initialCountryCode: CountryCode.gb,
                style: CountrifyFieldStyle.filledStyle(
                  fillColor: _C.slate100,
                  focusedBorderColor: _C.teal,
                ).copyWith(
                  hintText: 'Filled variant',
                  cursorColor: _C.teal,
                ),
                onChanged: (_, __) {},
              )
```

--------------------------------

### Build Selection Row Widget

Source: https://pub.dev/packages/countrify/example

Helper widget to build a row displaying a label, optional flag, and a value for selection details. Handles ellipsis for long values.

```dart
Widget _buildSelectionRow(
      String label, String? value, String? flag) {
    return Row(
      children: [
        SizedBox(
          width: 60,
          child: Text(
            label,
            style: const TextStyle(
              fontSize: 13,
              color: _C.slate400,
              fontWeight: FontWeight.w500,
            ),
          ),
        ),
        if (flag != null) ...[
          Text(flag, style: const TextStyle(fontSize: 16)),
          const SizedBox(width: 6),
        ],
        Flexible(
          child: Text(
            value ?? '--',
            style: TextStyle(
              fontSize: 14,
              fontWeight: FontWeight.w600,
              color: value != null ? _C.slate900 : _C.slate400,
            ),
            overflow: TextOverflow.ellipsis,
          ),
        ),
      ],
    );
  }
```

--------------------------------

### Get All Translations for a Country

Source: https://pub.dev/packages/countrify

Retrieve a map of all available translations for a given country using `CountryUtils.getCountryNamesInAllLanguages`. This map contains locale codes as keys and translated country names as values.

```dart
final usa = CountryUtils.getCountryByAlpha2Code('US')!;
final allNames = CountryUtils.getCountryNamesInAllLanguages(usa);
// Returns a Map<String, String> with 130+ entries:
// {"af": "Verenigde State van Amerika", "ar": "الولايات المتحدة", "de": "Vereinigte Staaten", ...}

```

--------------------------------

### Applying a Theme to CountryPicker

Source: https://pub.dev/packages/countrify

Apply a chosen theme, such as CountryPickerTheme.darkTheme(), to the CountryPicker widget by passing it to the theme parameter.

```dart
CountryPicker(
  onCountrySelected: (country) { },
  theme: CountryPickerTheme.darkTheme(),
)
```

--------------------------------

### Get All Country Names for a Specific Locale

Source: https://pub.dev/packages/countrify

Retrieve all country names translated for a given locale using `CountryNameL10n.getTranslationsForLocale`. This returns a map where keys are country codes and values are translated names.

```dart
import 'package:countrify/countrify.dart';

// Get all country names for a locale
final frenchNames = CountryNameL10n.getTranslationsForLocale('fr');
// {"AD": "Andorre", "AE": "Émirats arabes unis", "AF": "Afghanistan", ...}

```

--------------------------------

### CountryUtils - Metadata Lookups

Source: https://pub.dev/packages/countrify

Utilities for retrieving lists of available metadata categories.

```APIDOC
## CountryUtils - Metadata Lookups

### Description
Provides methods to get lists of available metadata categories.

### Methods
- **getAllRegions()**: Returns a list of all available regions.
- **getAllSubregions()**: Returns a list of all available subregions.
- **getAllCurrencies()**: Returns a list of all available currency codes.
- **getAllLanguages()**: Returns a list of all available language codes.
- **getAllTimezones()**: Returns a list of all available timezone identifiers.

### Examples
```dart
final regions = CountryUtils.getAllRegions();         // ["Africa", "Americas", ...]
final subregions = CountryUtils.getAllSubregions();   // ["Caribbean", "Central Asia", ...]
final currencies = CountryUtils.getAllCurrencies();
final languages = CountryUtils.getAllLanguages();
final timezones = CountryUtils.getAllTimezones();
```
```

--------------------------------

### StatePicker

Source: https://pub.dev/packages/countrify

A standalone picker for states/provinces/regions of a single country. Supports various display modes, sorting, theming, and custom builders.

```APIDOC
## StatePicker

### Description
Standalone picker for the states / provinces / regions of a single country. Supports four display modes (`bottomSheet`, `dialog`, `fullScreen`, `dropdown`) and is fully themeable.

### Parameters
- **countryIso2** (String) - The ISO2 code of the country to fetch states for.
- **initialStateId** (dynamic) - The ID of the initially selected state.
- **pickerMode** (CountryPickerMode) - The display mode for the picker.
- **sortBy** (StateSortBy) - The criteria for sorting states.
- **theme** (GeoPickerTheme) - The theme for the picker.
- **config** (GeoPickerConfig) - Configuration options for the picker.
- **customStateBuilder** ((BuildContext, CountryState, bool) => Widget) - A custom builder for state rows.
- **onStateSelected** ((CountryState) => void) - Callback when a state is selected.
- **onSearchChanged** ((String) => void) - Callback when the search query changes.
- **onResultsChanged** ((List<CountryState>) => void) - Callback when search results change.
- **customMatcher** ((CountryState, String) => bool) - Custom logic for matching states against a query.
- **customSearchBuilder** ((BuildContext, TextEditingController) => Widget) - Custom builder for the search input field.

### Example (Basic)
```dart
StatePicker(
  countryIso2: 'US',
  initialStateId: 1416,
  pickerMode: CountryPickerMode.bottomSheet,
  sortBy: StateSortBy.name,
  theme: GeoPickerTheme.light(),
  config: const GeoPickerConfig(
    title: 'Pick your state',
    searchHintText: 'Search states',
    hapticFeedback: true,
  ),
  customStateBuilder: (ctx, state, selected) => Row(
    children: [
      Expanded(child: Text(state.name)),
      if (state.iso2 != null) Text(state.iso2!),
    ],
  ),
  onStateSelected: (state) => print(state.name),
)
```

### Example (Search Configuration)
```dart
StatePicker(
  countryIso2: 'BR',
  config: const GeoPickerConfig(
    initialSearchText: 'sao',
    searchDebounce: Duration(milliseconds: 200),
    accentInsensitiveSearch: true,
    autofocusSearch: true,
  ),
  onSearchChanged: (q) => print('typed: $q'),
  onResultsChanged: (results) => print('${results.length} match'),
  customMatcher: (state, query) =>
      state.name.toLowerCase().contains(query) ||
      (state.iso2?.toLowerCase() == query),
  onStateSelected: (s) => print(s.name),
)
```

### Example (Custom Search Builder)
```dart
StatePicker(
  countryIso2: 'US',
  customSearchBuilder: (context, controller) => TextField(
    controller: controller,
    decoration: InputDecoration(
      prefixIcon: const Icon(Icons.travel_explore),
      labelText: 'Find your state',
      border: OutlineInputBorder(borderRadius: BorderRadius.circular(30)),
    ),
  ),
  onStateSelected: (s) => print(s.name),
)
```
```

--------------------------------

### Get Localized Country Name via CountryNameL10n

Source: https://pub.dev/packages/countrify

Access localized country names directly using `CountryNameL10n.getLocalizedName` for a specific country code and locale. This offers lower-level access compared to `CountryUtils`.

```dart
import 'package:countrify/countrify.dart';

// Get a single translation
final name = CountryNameL10n.getLocalizedName('DE', 'fr'); // "Allemagne"

```

--------------------------------

### Get Localized Country Name Programmatically

Source: https://pub.dev/packages/countrify

Use `CountryUtils.getCountryNameInLanguage` to retrieve the localized name of a country for a given language code. This method first checks for user-provided translations and falls back to CLDR data.

```dart
final usa = CountryUtils.getCountryByAlpha2Code('US')!;

CountryUtils.getCountryNameInLanguage(usa, 'de'); // "Vereinigte Staaten"
CountryUtils.getCountryNameInLanguage(usa, 'fr'); // "États-Unis"
CountryUtils.getCountryNameInLanguage(usa, 'ja'); // "アメリカ合衆国"
CountryUtils.getCountryNameInLanguage(usa, 'ar'); // "الولايات المتحدة"
CountryUtils.getCountryNameInLanguage(usa, 'zh'); // "美国"
CountryUtils.getCountryNameInLanguage(usa, 'hi'); // "संयुक्त राज्य"

```

--------------------------------

### Fetch Countries by Currency Code

Source: https://pub.dev/packages/countrify

Retrieve countries that use a specific currency by its ISO 4217 code using CountryUtils.getCountriesByCurrencyCode().

```dart
// Get by currency
final euroCountries = CountryUtils.getCountriesByCurrencyCode('EUR');

```
Tokens:
Raw