country_search 3.0.1

Localized Flutter country picker with fast search, flexible Builder API, and standalone CountryFlag emoji/svg widgets.

country_search

Simple and fast country picker for Flutter.

Live version · pub.dev · Repository · Issues · Changelog · Migration

What You Get

• 252+ countries (ISO code, emoji flag, phone code)
• Fast search by name, ISO code, and phone code
• 21 localizations
• Builder API for customization
• Standalone CountryFlag widget (emoji/svg)

Supported Translation Languages

ar Arabic, bn Bengali, de German, en English, es Spanish, fr French, hi Hindi, id Indonesian, it Italian, ja Japanese, ko Korean, nl Dutch, pl Polish, pt Portuguese, ru Russian, th Thai, tr Turkish, uk Ukrainian, ur Urdu, vi Vietnamese, zh Chinese.

Install

dependencies:
  country_search: ^3.0.1

1-Minute Setup

import 'package:country_search/country_search.dart';
import 'package:flutter_localizations/flutter_localizations.dart';

MaterialApp(
  localizationsDelegates: const [
    CountryLocalizations.delegate,
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  supportedLocales: CountryLocalizations.supportedLocales,
  home: const DemoPage(),
);

CountryPicker.builder()
    .selectedCountry(selectedCountry)
    .onCountrySelected((country) {
      setState(() => selectedCountry = country);
    })
    .build();

Most Used Options

CountryPicker.builder()
    .favorites(const ['US', 'GB'])
    .exclude(const ['RU'])
    .countryFilter((country) => country.code != 'KP')
    .onOpened(() {})
    .onClosed(() {})
    .onSearchChanged((query) {})
    .showSuggestedCountries(true)
    .modalPresentation(CountryPickerModalPresentation.dialog)
    .build();

Styling (3.x)

In 3.x, styling goes through CountryPickerThemeData only.

final theme = CountryPickerThemeData.light.copyWith(
  accentColor: Colors.blue,
  borderRadius: 12,
  itemHeight: 56,
);

CountryPicker.builder()
    .themeData(theme)
    .build();

Built-in presets:

• CountryPickerThemeData.dark
• CountryPickerThemeData.light
• CountryPickerThemeData.purple
• CountryPickerThemeData.minimal

CountryFlag Widget

CountryFlag.fromCountryCode('US');

CountryFlag.fromCountryCode(
  'JP',
  mode: CountryFlagMode.svg,
  style: const CountryFlagStyle(size: 24, isCircle: true),
);

Lookup constructors:

• CountryFlag.fromLanguageCode('pt-BR')
• CountryFlag.fromCurrencyCode('USD')
• CountryFlag.fromPhoneCode('+44')

Search Rules

• Empty query:
  • showSuggestedCountries = true: suggested + regular sections
  • showSuggestedCountries = false: regular list only
• Non-empty query ranking: exact -> startsWith -> contains -> fuzzy
• Accent-insensitive (etats finds États-Unis)
• Phone normalization (+380, 380, (+380) work)

Migration From 2.x

3.0.0 removed legacy constructor style fields. Use themeData for styling.

See MIGRATION.md.

Compatibility

• Dart: >=3.0.0 <4.0.0
• Flutter: >=3.0.0

Dev

flutter analyze
flutter test

License

MIT. See LICENSE.