Akeng.CountryPicker 1.5.4

Akeng.CountryPicker

A lightweight and customizable .NET MAUI country and international phone input library. If you find Akeng.SignaturePad useful, consider giving the repository a ⭐.

Controls

• 🌍 CountryPickerView — searchable and customizable country picker
• 📱 PhoneEntryView — international phone number input with country selection, formatting and validation
• 🧭 CountryPickerButtonView — compact country selector for forms and lightweight UIs
• 📞 DialCodePickerView — compact international dialing code selector
• 🔍 CountryAutoCompleteView — real-time searchable country autocomplete
• 🏳️ CountryFlagView — reusable country flag renderer with Image and Emoji support
• 🪪 CountryCardView — elegant country information card
• 🌍 CountryMultiPickerView — searchable multiple-country selector with chips and selection limits

Highlights

• 🌍 240+ countries
• 📞 International dialing codes
• 🏳️ Country flags and emojis
• 🔍 Built-in country search
• ⭐ Favorite and recent countries
• 🧭 Compact country selector for forms and lightweight UIs
• 🌐 Automatic country detection
• 📱 International phone number validation
• ⚡ Phone number formatting while typing
• 🌐 E.164 phone number support
• 📋 International number detection
• 🎨 Light / Dark / System themes
• 🧩 MVVM support
• 📱 Android, iOS, Windows and MacCatalyst

---

🌍 CountryPickerView

A lightweight and customizable .NET MAUI Country Picker for Android, iOS, Windows and MacCatalyst.

✨ Features

• 🌍 240+ countries
• 📞 International dialing codes
• 🏳️ Country emoji / flag support
• 🔍 Fast built-in search
• ⭐ Favorite countries
• 🕘 Recent countries
• 🌐 Device region detection
• 📍 Optional geolocation-based country detection
• 🎨 Light, Dark and System themes
• 🧩 Built-in item templates
• 🎛️ Fully custom DataTemplate
• 🔄 Two-way selected country binding
• ⚡ MVVM command support
• 🧩 ICountryService for fully custom UIs
• 📱 Android, iOS, Windows and MacCatalyst

---

Installation

dotnet add package Akeng.CountryPicker

Register the package in MauiProgram.cs:

using AkengCountryPicker.Extensions;

builder
    .UseMauiApp<App>()
    .UseAkengMauiCountryPicker();

---

Usage

Option 1 — Use ICountryService

public class HomeViewModel
{
    private readonly ICountryService _countryService;

    public HomeViewModel(ICountryService countryService)
    {
        _countryService = countryService;
    }

    public async Task LoadAsync()
    {
        var countries = await _countryService.GetCountriesAsync();
    }
}

Available methods:

Task<List<CountryInfo>> GetCountriesAsync();
Task<List<CountryInfo>> SearchAsync(string text);
Task<CountryInfo?> GetByIso2Async(string iso2);
Task<CountryInfo?> GetByIso3Async(string iso3);
Task<CountryInfo?> GetByDialCodeAsync(string dialCode);
Task<CountryInfo?> GetCurrentCountryAsync();

---

Option 2 — Use CountryPickerView

xmlns:countryPicker="clr-namespace:AkengCountryPicker.Controls;assembly=AkengCountryPicker"

<countryPicker:CountryPickerView
    SelectedCountry="{Binding SelectedCountry}" />

ViewModel:

public CountryInfo? SelectedCountry
{
    get => _selectedCountry;
    set => SetProperty(ref _selectedCountry, value);
}

---

Customization

Property	Default	Description
ShowEmoji	True	Show country emoji
ShowDialCode	True	Show dialing code
ShowSearchBar	True	Show search bar
ShowNativeName	True	Show native country name
ShowIso2	False	Show ISO2
ShowIso3	False	Show ISO3
ShowFavorites	True	Show favorites group
ShowRecentCountries	True	Show recent countries
AllowFavoriteSelection	True	Allow favorite toggle
MaxRecentCountries	5	Maximum recent countries
DetectionMode	None	Country detection mode
Theme	System	Picker theme
TemplateMode	Default	Built-in item layout
Placeholder	Search country...	Search placeholder
EmptyMessage	No country found	Empty result message

---

Country Selection

Event-based:

<countryPicker:CountryPickerView
    CountrySelected="OnCountrySelected" />

private void OnCountrySelected(object sender, CountryInfo country)
{
    Debug.WriteLine(country.Name);
}

MVVM command:

<countryPicker:CountryPickerView
    SelectedCountry="{Binding SelectedCountry}"
    CountrySelectedCommand="{Binding CountrySelectedCommand}" />

---

🌍 Automatic Country Detection

<countryPicker:CountryPickerView
    DetectionMode="Geolocation" />

Available modes:

None
DeviceRegion
Geolocation

Android permissions

Add to Platforms/Android/AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

iOS / MacCatalyst

Add to Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>This application uses your location to automatically select your current country.</string>

Geolocation is optional. No location permission is required unless DetectionMode="Geolocation" is used.

---

🎨 Themes

Available themes:

System
Light
Dark

<countryPicker:CountryPickerView
    Theme="Dark" />

Change at runtime:

countryPicker.Theme = CountryPickerTheme.Dark;
countryPicker.Theme = CountryPickerTheme.Light;
countryPicker.Theme = CountryPickerTheme.System;

The picker theme only affects CountryPickerView, not the entire application.

---

🧩 Built-in Templates

Available template modes:

• Default
• Compact
• Phone
• Iso
• NativeName
• FlagOnly

<countryPicker:CountryPickerView
    TemplateMode="Phone" />

Change at runtime:

countryPicker.TemplateMode = CountryItemTemplateMode.Compact;

---

🎛️ Custom Country Template

You can completely replace the built-in item layout.

xmlns:countryModels="clr-namespace:AkengCountryPicker.Models;assembly=AkengCountryPicker"

<countryPicker:CountryPickerView>

    <countryPicker:CountryPickerView.CountryTemplate>

        <DataTemplate x:DataType="countryModels:CountryInfo">

            <Grid
                Padding="12"
                ColumnDefinitions="Auto,*,Auto">

                <Label
                    FontSize="26"
                    Text="{Binding FlagEmoji}" />

                <VerticalStackLayout
                    Grid.Column="1"
                    Margin="12,0">

                    <Label
                        FontAttributes="Bold"
                        Text="{Binding Name}" />

                    <Label
                        FontSize="12"
                        Text="{Binding DialCode}" />

                </VerticalStackLayout>

            </Grid>

        </DataTemplate>

    </countryPicker:CountryPickerView.CountryTemplate>

</countryPicker:CountryPickerView>

A custom CountryTemplate takes priority over TemplateMode.

The picker still keeps its built-in search, selection, recent countries and favorites logic.

---

⭐ Favorites & Recent Countries

The picker automatically:

• persists favorite countries
• remembers recently selected countries
• avoids duplicates
• limits recent countries with MaxRecentCountries
• updates the groups in real time

Favorites and recent countries are stored locally using country ISO2 codes.

---

Country Model

public class CountryInfo
{
    public string Name { get; set; } = string.Empty;
    public string NativeName { get; set; } = string.Empty;
    public string Iso2 { get; set; } = string.Empty;
    public string Iso3 { get; set; } = string.Empty;
    public string DialCode { get; set; } = string.Empty;
    public string FlagEmoji { get; set; } = string.Empty;

    public bool IsFavorite { get; set; }

    public string FavoriteIcon =>
        IsFavorite ? "★" : "☆";
}

---

📱 PhoneEntryView

PhoneEntryView is a customizable international phone number input control for .NET MAUI.

It combines country selection, international dialing codes, phone number formatting, validation, and automatic country detection in a single control.

Features

• 🌍 Country selection using CountryPickerView
• 🏳️ Country flag and dialing code
• 📞 International phone number input
• ⚡ Formatting while typing
• ✅ Phone number validation
• 🌐 E.164 phone number generation
• 🔍 Automatic country detection
• 📋 International number paste detection
• 🔄 Automatic country switching from international numbers
• 🚫 Protection against excessively long phone numbers
• 🎨 Light, Dark and System themes
• 🧩 MVVM-friendly properties and commands

Phone number parsing, formatting, and validation are powered by libphonenumber.

---

Basic Usage

<countryPicker:PhoneEntryView
    SelectedCountry="{Binding SelectedCountry}"
    PhoneNumber="{Binding PhoneNumber}" />

ViewModel:

[ObservableProperty]
private CountryInfo? selectedCountry;

[ObservableProperty]
private string phoneNumber = string.Empty;

---

Automatic Country Detection

PhoneEntryView supports the same country detection modes as CountryPickerView.

<countryPicker:PhoneEntryView
    DetectionMode="DeviceRegion"
    PhoneNumber="{Binding PhoneNumber}" />

Available modes:

Mode	Description
None	No automatic country detection
DeviceRegion	Uses the device region settings
Geolocation	Uses the device location

When using Geolocation, the required location permissions must be configured as described in the Automatic Country Detection section above.

---

Phone Number Validation

PhoneEntryView automatically validates the number according to the selected country's numbering rules.

<countryPicker:PhoneEntryView
    SelectedCountry="{Binding SelectedCountry}"
    PhoneNumber="{Binding PhoneNumber}"
    ShowValidationIcon="True"
    ShowFullPhoneNumber="True" />

The control exposes:

Property	Description
PhoneNumber	Phone number displayed and edited by the user
FullPhoneNumber	Normalized international number in E.164 format
SelectedCountry	Currently selected country
IsPossible	Indicates whether the number has a possible structure
IsValid	Indicates whether the number is valid
ValidationState	Detailed phone number validation state

Validation States

ValidationState can return:

PhoneValidationState.Empty
PhoneValidationState.TooShort
PhoneValidationState.TooLong
PhoneValidationState.InvalidLength
PhoneValidationState.InvalidCountryCode
PhoneValidationState.Possible
PhoneValidationState.PossibleLocalOnly
PhoneValidationState.Valid
PhoneValidationState.Invalid

Example:

if (phoneEntry.ValidationState == PhoneValidationState.Valid)
{
    var internationalNumber = phoneEntry.FullPhoneNumber;
}

---

E.164 Format

When a valid phone number is entered, FullPhoneNumber provides its normalized international representation.

For example:

Country: Cameroon
Dial code: +237
PhoneNumber: 677 123 456

FullPhoneNumber: +237677123456

This format is suitable for storing phone numbers or sending them to an API.

---

International Number Detection

PhoneEntry can recognize an international number entered or pasted by the user. The SelectedCountry, dialing code, formatted number, validation state, and E.164 value are updated automatically.

---

MVVM Commands

PhoneEntry provides commands for common interactions.

<countryPicker:PhoneEntry
    SelectedCountry="{Binding SelectedCountry}"
    PhoneNumber="{Binding PhoneNumber}"
    CountryChangedCommand="{Binding CountryChangedCommand}"
    PhoneNumberChangedCommand="{Binding PhoneNumberChangedCommand}"
    ValidationChangedCommand="{Binding ValidationChangedCommand}" />

Example with CommunityToolkit.Mvvm:

[RelayCommand]
private void CountryChanged(CountryInfo country)
{
    Debug.WriteLine($"Country: {country.Name}");
}

[RelayCommand]
private void PhoneNumberChanged(string phoneNumber)
{
    Debug.WriteLine($"Phone: {phoneNumber}");
}

[RelayCommand]
private void ValidationChanged(
    PhoneValidationChangedEventArgs result)
{
    Debug.WriteLine($"State: {result.State}");
    Debug.WriteLine($"Valid: {result.IsValid}");
    Debug.WriteLine($"E164: {result.FullPhoneNumber}");
}

---

🎨 PhoneEntryView Themes

PhoneEntryView supports the same themes as CountryPickerView.

<countryPicker:PhoneEntryView
    Theme="System" />

Available themes:

• System — follows the application theme
• Light — forces the light theme
• Dark — forces the dark theme

The theme applies only to the control and does not change the application's global theme.

---

🎨 PhoneEntryView Customization

PhoneEntryView inherits common visual properties from CountryControlBase.

Example:

<countryPicker:PhoneEntryView
    Theme="Dark"
    BorderColor="#00A8FF"
    BorderThickness="2"
    CornerRadius="16"
    PrimaryTextColor="White"
    SecondaryTextColor="#AAAAAA"
    SurfaceColor="#202020"
    SuccessColor="#34C759"
    ErrorColor="#FF453A"
    ControlFontSize="16"
    ControlPadding="14,8"
    ControlSpacing="10"
    PhoneNumber="{Binding PhoneNumber}" />

This allows PhoneEntryView and CountryPickerView to share a consistent visual style while still being independently customizable.

---

Complete Example

<countryPicker:PhoneEntryView
    DetectionMode="DeviceRegion"
    Theme="System"
    SelectedCountry="{Binding SelectedCountry}"
    PhoneNumber="{Binding PhoneNumber}"
    ShowValidationIcon="True"
    ShowFullPhoneNumber="True"
    CountryChangedCommand="{Binding CountryChangedCommand}"
    ValidationChangedCommand="{Binding ValidationChangedCommand}" />

PhoneEntryView handles country selection, formatting, validation, and international phone number normalization while remaining fully compatible with MVVM.

---

🧭 CountryPickerButtonView

CountryPickerButtonView is a compact and reusable country selector for .NET MAUI.

It displays the currently selected country in a button-like control and opens the built-in CountryPickerView when tapped.

It is ideal for forms, settings pages, profile screens, filters, and compact layouts where displaying the full country list is not appropriate.

Features

• 🌍 Country selection using the built-in picker
• 🏳️ Country flag / emoji support
• 📞 Dial code display
• 🆔 ISO2 display
• 🌐 Automatic country detection
• 🎨 Light, Dark and System themes
• ⚡ MVVM command support
• 🔄 Two-way SelectedCountry binding
• 🎛️ Multiple display modes
• 🧩 Reuses the same picker infrastructure as PhoneEntryView

---

Basic Usage

<countryPicker:CountryPickerButtonView
    SelectedCountry="{Binding SelectedCountry}" />

---

Display Modes

CountryPickerButtonView supports several display modes:

CountryButtonDisplayMode.FlagAndName
CountryButtonDisplayMode.FlagAndDialCode
CountryButtonDisplayMode.FlagAndIso2
CountryButtonDisplayMode.FlagOnly
CountryButtonDisplayMode.NameOnly
CountryButtonDisplayMode.DialCodeOnly

Example:

<countryPicker:CountryPickerButtonView
    SelectedCountry="{Binding SelectedCountry}"
    DisplayMode="FlagAndName" />

---

Automatic Country Detection

CountryPickerButtonView supports the same detection modes as the other controls.

<countryPicker:CountryPickerButtonView
    DetectionMode="DeviceRegion" />

Available modes:

Mode	Description
None	No automatic detection
DeviceRegion	Uses the device region
Geolocation	Uses the device geographic location

Geolocation requires the platform permissions documented in the automatic country detection section.

---

MVVM

<countryPicker:CountryPickerButtonView
    SelectedCountry="{Binding SelectedCountry}"
    CountryChangedCommand="{Binding CountryChangedCommand}" />

Example with CommunityToolkit.Mvvm:

[ObservableProperty]
private CountryInfo? selectedCountry;

[RelayCommand]
private void CountryChanged(CountryInfo country)
{
    Debug.WriteLine($"Selected country: {country.Name}");
}

---

Customization

CountryPickerButtonView inherits the common visual options provided by CountryControlBase.

<countryPicker:CountryPickerButtonView
    Theme="Dark"
    DisplayMode="FlagAndName"
    BorderColor="#00A8FF"
    BorderThickness="2"
    CornerRadius="14"
    SurfaceColor="#202020"
    PrimaryTextColor="White"
    SecondaryTextColor="#AAAAAA"
    ControlPadding="14,8"
    ControlSpacing="10" />

---

Main Properties

Property	Default	Description
SelectedCountry	null	Currently selected country
DisplayMode	FlagAndName	Controls the displayed country information
DetectionMode	None	Automatic country detection mode
Placeholder	Select a country	Text displayed when no country is selected
ShowFlag	True	Displays the country flag
ShowArrow	True	Displays the picker arrow
Theme	System	Control theme
IsPickerOpen	False	Indicates whether the picker is currently open

---

Events and Commands

Available APIs:

CountryChanged
CountryChangedCommand
ClickedCommand

Example:

<countryPicker:CountryPickerButtonView
    CountryChanged="OnCountryChanged"
    CountryChangedCommand="{Binding CountryChangedCommand}" />

---

📞 DialCodePickerView

DialCodePickerView is a compact .NET MAUI control designed for selecting an international dialing code together with its associated country.

It is ideal for custom phone forms where you want to manage the phone input yourself while reusing the country selection capabilities provided by Akeng.CountryPicker.

Features

• 📞 International dialing code selection
• 🌍 Country selection using the built-in picker
• 🏳️ Optional country flag / emoji
• 🔽 Optional picker arrow
• 🌐 Automatic country detection
• 🔄 Two-way SelectedCountry binding
• ⚡ MVVM command support
• 🎨 Light, Dark and System themes
• 🖌️ Customizable colors, border, spacing and typography
• ♻️ Reuses the same picker infrastructure as CountryPickerButtonView and PhoneEntryView

---

Basic Usage

<countryPicker:DialCodePickerView
    SelectedCountry="{Binding SelectedCountry}" />

---

Automatic Country Detection

DialCodePickerView supports the same detection modes as the other country controls.

<countryPicker:DialCodePickerView
    DetectionMode="DeviceRegion"
    SelectedCountry="{Binding SelectedCountry}" />

Available modes:

Mode	Description
None	No automatic detection
DeviceRegion	Uses the device region settings
Geolocation	Uses the current geographic location

Geolocation requires the platform permissions documented in the automatic country detection section.

---

Selected Dial Code

The currently selected dialing code is exposed through:

dialCodePicker.SelectedDialCode

Example:

SelectedCountry: Cameroon
SelectedDialCode: +237

SelectedDialCode is updated automatically whenever SelectedCountry changes.

---

MVVM

DialCodePickerView exposes both country and dial-code change notifications.

<countryPicker:DialCodePickerView
    SelectedCountry="{Binding SelectedCountry}"
    CountryChangedCommand="{Binding CountryChangedCommand}"
    DialCodeChangedCommand="{Binding DialCodeChangedCommand}" />

Example with CommunityToolkit.Mvvm:

[ObservableProperty]
private CountryInfo? selectedCountry;

[RelayCommand]
private void CountryChanged(CountryInfo country)
{
    Debug.WriteLine($"Country: {country.Name}");
}

[RelayCommand]
private void DialCodeChanged(string dialCode)
{
    Debug.WriteLine($"Dial code: {dialCode}");
}

---

Events

You can also use events:

<countryPicker:DialCodePickerView
    CountryChanged="OnCountryChanged"
    DialCodeChanged="OnDialCodeChanged" />

private void OnCountryChanged(object sender,  CountryInfo country)
{
    Debug.WriteLine(country.Name);
}

private void OnDialCodeChanged( object sender, string dialCode)
{
    Debug.WriteLine(dialCode);
}

---

Themes

DialCodePickerView inherits the common theme system from CountryControlBase.

<countryPicker:DialCodePicker
    Theme="Dark" />

Available themes:

• System
• Light
• Dark

The selected theme affects only the control and does not modify the application's global theme.

---

Main Properties

Property	Default	Description
SelectedCountry	null	Currently selected country
SelectedDialCode	""	Dialing code of the selected country
DetectionMode	None	Automatic country detection mode
ShowFlag	True	Displays the country flag
ShowArrow	True	Displays the picker arrow
Theme	System	Control theme
IsPickerOpen	False	Indicates whether the country picker is open

---

Commands

Available MVVM commands:

CountryChangedCommand
DialCodeChangedCommand
ClickedCommand

---

Example

<countryPicker:DialCodePicker
    DetectionMode="DeviceRegion"
    Theme="System"
    SelectedCountry="{Binding SelectedCountry}"
    ShowFlag="True"
    ShowArrow="True"
    DialCodeChangedCommand="{Binding DialCodeChangedCommand}" />

DialCodePicker is useful when you need international dialing-code selection without using the full PhoneEntry control.

---

---

🔍 CountryAutoCompleteView

CountryAutoCompleteView is a searchable and customizable .NET MAUI country autocomplete control.

It allows users to quickly find and select a country by typing its name, native name, ISO code, or international dialing code.

It is ideal for forms and interfaces where fast country search is preferred over opening a full country picker.

Features

• 🔍 Real-time country search
• 🌍 240+ countries
• 🏳️ Country flags / emojis
• 📞 International dialing codes
• 🆔 ISO2 / ISO3 search
• 🌐 Native country name search
• ⚡ Debounced search for better performance
• 🎯 Smart result ranking
• 📋 Configurable maximum suggestions
• 🔄 Two-way SelectedCountry binding
• 🌐 Automatic country detection
• 🎨 Light, Dark and System themes
• 🧩 MVVM events and commands
• 🚫 Built-in no-results state
• ♻️ Shared infrastructure with the other country controls

---

Basic Usage

<countryPicker:CountryAutoCompleteView
    SelectedCountry="{Binding SelectedCountry}" />

Search

Countries can be searched using:

• Country name
• Native name
• ISO2 code
• ISO3 code
• International dialing code

The search engine prioritizes exact matches and results that start with the entered text.

---

Search Configuration

Control when suggestions start appearing:

<countryPicker:CountryAutoCompleteView
    MinimumCharacters="2"
    MaxSuggestions="5" />

Property	Default	Description
MinimumCharacters	1	Minimum number of characters required before searching
MaxSuggestions	6	Maximum number of displayed suggestions
SuggestionsMaxHeight	280	Maximum height of the suggestions panel

Search input is debounced to avoid unnecessary filtering while the user is typing.

---

Display Options

Control the information displayed in suggestions:

<countryPicker:CountryAutoCompleteView
    ShowFlag="True"
    ShowDialCode="True"
    ShowIso2="True" />

Available options:

Property	Default	Description
ShowFlag	True	Displays the country flag
ShowDialCode	True	Displays the international dialing code
ShowIso2	False	Displays the ISO2 country code

---

Automatic Country Detection

CountryAutoCompleteView supports the common country detection system.

<countryPicker:CountryAutoComplete
    DetectionMode="DeviceRegion"
    SelectedCountry="{Binding SelectedCountry}" />

Available modes:

Mode	Description
None	No automatic country detection
DeviceRegion	Uses the device region settings
Geolocation	Uses the current geographic location

When a country is automatically detected, the control updates both SelectedCountry and the displayed country name.

Geolocation requires the platform permissions documented in the Automatic Country Detection section.

---

MVVM

<countryPicker:CountryAutoCompleteView
    SelectedCountry="{Binding SelectedCountry}"
    SearchText="{Binding CountrySearch}"
    CountryChangedCommand="{Binding CountryChangedCommand}"
    SearchTextChangedCommand="{Binding SearchTextChangedCommand}" />

Example with CommunityToolkit.Mvvm:

[ObservableProperty]
private CountryInfo? selectedCountry;

[ObservableProperty]
private string countrySearch = string.Empty;

[RelayCommand]
private void CountryChanged(CountryInfo country)
{
    Debug.WriteLine($"Country: {country.Name}");
}

[RelayCommand]
private void SearchTextChanged(string searchText)
{
    Debug.WriteLine($"Search: {searchText}");
}

---

Events

Event-based usage is also supported:

<countryPicker:CountryAutoCompleteView
    CountryChanged="OnCountryChanged"
    SearchTextChanged="OnSearchTextChanged" />

private void OnCountryChanged(
    object sender,
    CountryInfo country)
{
    Debug.WriteLine(country.Name);
}

private void OnSearchTextChanged(
    object sender,
    string searchText)
{
    Debug.WriteLine(searchText);
}

---

Themes

CountryAutoCompleteView supports the common Akeng.CountryPicker theme system:

<countryPicker:CountryAutoCompleteView
    Theme="Dark" />

Available themes:

• System
• Light
• Dark

The theme applies only to the control and does not modify the application's global theme.

---

Customization

<countryPicker:CountryAutoCompleteView
    Theme="Dark"

    BorderColor="#00A8FF"
    BorderThickness="2"
    CornerRadius="14"

    SurfaceColor="#202020"
    PrimaryTextColor="White"
    SecondaryTextColor="#AAAAAA"

    ControlFontSize="16"
    ControlPadding="12,8"
    ControlSpacing="8"

    SuggestionsMaxHeight="250" />

---

Control State

CountryAutoCompleteView exposes several useful states:

countryAutoComplete.HasSelectedCountry
countryAutoComplete.IsSuggestionsVisible
countryAutoComplete.HasNoResults
countryAutoComplete.IsSearching

These properties can be used to build custom UI behavior around the control.

---

Public Methods

The current selection can be cleared programmatically:

countryAutoComplete.ClearSelection();

Focus can also be controlled:

countryAutoComplete.FocusSearch();

countryAutoComplete.UnfocusSearch();

---

Main Properties

Property	Default	Description
SelectedCountry	null	Currently selected country
SearchText	""	Current search text
Placeholder	Search country...	Search field placeholder
MinimumCharacters	1	Minimum characters before searching
MaxSuggestions	6	Maximum number of suggestions
SuggestionsMaxHeight	280	Maximum suggestion panel height
ShowFlag	True	Displays country flags
ShowDialCode	True	Displays dialing codes
ShowIso2	False	Displays ISO2 codes
DetectionMode	None	Automatic country detection
Theme	System	Control theme

---

Complete Example

<countryPicker:CountryAutoCompleteView
    SelectedCountry="{Binding SelectedCountry}"
    SearchText="{Binding CountrySearch}"

    Placeholder="Search country..."
    MinimumCharacters="1"
    MaxSuggestions="6"

    ShowFlag="True"
    ShowDialCode="True"
    ShowIso2="False"

    DetectionMode="DeviceRegion"
    Theme="System"

    CountryChangedCommand="{Binding CountryChangedCommand}" />

CountryAutoCompleteView provides a fast and compact alternative to the full country picker when users need to search and select countries directly from a form.

---

🏳️ CountryFlagView

CountryFlagView is a lightweight and reusable .NET MAUI country flag control.

It provides a centralized way to display country flags across Akeng.CountryPicker using either native flag emojis or packaged flag images.

The control can resolve a flag directly from a CountryInfo instance or from an ISO2 country code.

Features

• 🏳️ 240+ country flags
• 🖼️ Built-in PNG flag assets
• 😀 Native flag emoji support
• 🔄 Automatic Emoji / Image rendering
• 🆔 Direct ISO2 support
• 📦 Flag assets automatically included with the NuGet package
• 🎯 Automatic fallback support
• 📐 Custom flag dimensions
• 🧩 Reusable across all Akeng.CountryPicker controls
• 📱 Android, iOS, Windows and MacCatalyst

---

Basic Usage

Display a flag directly from an ISO2 code:

<countryPicker:CountryFlagView
    Iso2="CM" />

Or bind a CountryInfo:

<countryPicker:CountryFlagView
    Country="{Binding SelectedCountry}" />

---

Flag Modes

CountryFlagView supports different rendering modes through FlagMode. Available modes:

Mode	Description
Auto	Automatically selects the appropriate rendering mode
Image	Uses the built-in country flag image
Emoji	Uses the native country flag emoji

---

Flag Size

Image dimensions can be customized:

<countryPicker:CountryFlagView
    Iso2="FR"
    FlagMode="Image"
    FlagWidth="40"
    FlagHeight="28" />

Emoji size can also be customized:

<countryPicker:CountryFlagView
    Iso2="FR"
    FlagMode="Emoji"
    FlagSize="30" />

---

Fallback

CountryFlagView supports fallback rendering when the preferred flag representation is unavailable.

<countryPicker:CountryFlagView
    Iso2="CM"
    FlagMode="Image"
    FallbackMode="Emoji" />

Available fallback modes:

Mode	Description
None	Displays nothing when the flag cannot be rendered
Emoji	Falls back to the country flag emoji
Iso2	Displays the ISO2 country code

---

MVVM

Bind directly to a selected country:

<countryPicker:CountryFlagView
    Country="{Binding SelectedCountry}"
    FlagMode="Auto" />

Example ViewModel:

[ObservableProperty]
private CountryInfo? selectedCountry;

When SelectedCountry changes, the displayed flag is automatically updated.

---

Shared Flag Rendering

CountryFlagView is designed to provide consistent flag rendering across the package.

It can be used by:

• CountryPickerView
• CountryAutoCompleteView
• CountryPickerButtonView
• DialCodePickerView
• PhoneEntryView

This means the same flag configuration can be used consistently across different controls.

---

Main Properties

Property	Default	Description
Country	null	Country represented by the control
Iso2	""	ISO2 code used to resolve the country
FlagMode	Auto	Flag rendering strategy
FallbackMode	Emoji	Rendering fallback
FlagWidth	32	Image flag width
FlagHeight	24	Image flag height
FlagSize	24	Emoji flag font size

---

Built-in Flag Assets

Flag images are included directly in the Akeng.CountryPicker NuGet package.

No additional images or resources need to be added to the consuming application.

Simply install the package and use:

<countryPicker:CountryFlagView
    Iso2="MA"
    FlagMode="Image" />

The corresponding flag asset is automatically resolved internally.

Applications using Akeng.CountryPicker do not need to copy flag images into their own Resources/Images directory.

---

🪪 CountryCardView

CountryCardView provides an elegant and reusable way to display country information.

It supports multiple layouts, visual styles, country flags, favorite management, selection state, and MVVM commands.

Basic Usage

<countryPicker:CountryCardView
    Country="{Binding SelectedCountry}" />

Detailed Card

<countryPicker:CountryCardView
    Country="{Binding SelectedCountry}"
    Layout="Detailed"
    CardStyle="Elevated"
    FlagMode="Image"
    ShowNativeName="True"
    ShowIso2="True"
    ShowIso3="True"
    ShowDialCode="True" />

Compact Card

<countryPicker:CountryCardView
    Country="{Binding SelectedCountry}"
    Layout="Compact"
    CardStyle="Outlined"
    FlagMode="Image" />

Layouts

Layout	Description
Default	Balanced card displaying the main country information
Compact	Single-row layout optimized for lists
Detailed	Rich layout displaying extended country information

Card Styles

Style	Description
Elevated	Card with background and shadow
Outlined	Card with visible border
Flat	Minimal card without elevation

Selectable Card

CountryCardView can also be used as an interactive country item.

<countryPicker:CountryCardView
    Country="{Binding Country}"
    IsSelectable="True"
    IsSelected="{Binding IsSelected}"
    CountryCommand="{Binding OpenCountryCommand}" />

Favorites

Favorite countries can be managed directly from the card.

<countryPicker:CountryCardView
    Country="{Binding SelectedCountry}"
    ShowFavoriteButton="True"
    FavoriteChangedCommand="{Binding FavoriteChangedCommand}" />

Favorites use the same persistent country history system as the other Akeng.CountryPicker controls.

Main Properties

Property	Default	Description
Country	null	Country displayed by the card
Layout	Default	Card layout
CardStyle	Elevated	Visual card style
FlagMode	Auto	Flag rendering mode
ShowNativeName	True	Displays the native country name
ShowIso2	True	Displays the ISO2 code
ShowIso3	True	Displays the ISO3 code
ShowDialCode	True	Displays the international dial code
ShowFavoriteButton	True	Displays the favorite action
IsSelectable	False	Enables card selection
IsSelected	False	Current selection state
CountryCommand	null	Command executed when the card is tapped
FavoriteChangedCommand	null	Command executed when favorite state changes

---

🌍 CountryMultiPickerView

CountryMultiPickerView provides searchable multiple-country selection with built-in flags, selected-country chips, selection limits, counters, and MVVM support.

Basic Usage

<countryPicker:CountryMultiPickerView
    SelectedCountries="{Binding SelectedCountries}"
    MaxSelection="5"
    ShowSearchBar="True"
    ShowSelectedChips="True"
    FlagMode="Image" />

Selected countries are exposed through a two-way bindable ObservableCollection<CountryInfo>.

[ObservableProperty]
private ObservableCollection<CountryInfo> selectedCountries = [];

Selection Limit

Use MaxSelection to restrict how many countries can be selected.

<countryPicker:CountryMultiPickerView
    MaxSelection="5"
    SelectedCountries="{Binding SelectedCountries}" />

0 means unlimited selection.

When the limit is reached, unselected countries become unavailable until a selected country is removed.

Selected Country Chips

Selected countries can be displayed as removable chips:

<countryPicker:CountryMultiPickerView
    ShowSelectedChips="True" />

Example:

[🇨🇲 Cameroon ×] [🇫🇷 France ×] [🇲🇦 Morocco ×]

Selection Counter

<countryPicker:CountryMultiPickerView
    MaxSelection="5"
    ShowSelectionCount="True" />

Example:

3 / 5

The control also exposes:

SelectedCount
IsSelectionFull
RemainingSelectionCount

Select All and Clear

Optional actions can be enabled:

<countryPicker:CountryMultiPickerView
    ShowSelectAllButton="True"
    ShowClearButton="True" />

The same operations are available programmatically:

countryMultiPicker.SelectAll();

countryMultiPicker.ClearSelection();

SelectAll automatically respects MaxSelection.

Search

Countries can be searched by:

• Country name
• Native name
• ISO2
• ISO3
• Dial code

<countryPicker:CountryMultiPickerView
    ShowSearchBar="True"
    Placeholder="Search countries..." />

An empty state is automatically displayed when no country matches the search.

The message can be customized:

<countryPicker:CountryMultiPickerView
    EmptyMessage="No matching country found" />

MVVM Commands

Selection changes can be handled directly from a ViewModel:

<countryPicker:CountryMultiPickerView
    SelectedCountries="{Binding SelectedCountries}"
    SelectionChangedCommand="{Binding SelectionChangedCommand}"
    SelectionLimitReachedCommand="{Binding SelectionLimitReachedCommand}" />

Example with CommunityToolkit.Mvvm:

[RelayCommand]
private void SelectionChanged(
    CountryMultiSelectionChangedEventArgs e)
{
    Debug.WriteLine(
        $"{e.ChangedCountry?.Name}: {e.IsSelected}");

    Debug.WriteLine(
        $"Selected countries: {e.SelectedCountries.Count}");
}

Selection limit:

[RelayCommand]
private void SelectionLimitReached(int maximum)
{
    Debug.WriteLine(
        $"Maximum selection reached: {maximum}");
}

Events

<countryPicker:CountryMultiPickerView
    SelectionChanged="OnSelectionChanged"
    SelectionLimitReached="OnSelectionLimitReached" />

Main Properties

Property	Default	Description
SelectedCountries	Empty	Two-way collection of selected countries
MaxSelection	0	Maximum selection (0 = unlimited)
ShowSearchBar	True	Displays country search
Placeholder	Search countries...	Search placeholder
ShowSelectedChips	True	Displays selected countries as chips
ShowSelectionCount	False	Displays the selection counter
ShowSelectAllButton	False	Displays the Select All action
ShowClearButton	False	Displays the Clear action
ShowNativeName	False	Displays native country names
ShowDialCode	True	Displays international dial codes
FlagMode	Auto	Flag rendering strategy
EmptyMessage	No country found	Empty search result message

Selection State

CountryMultiPickerView exposes useful read-only selection information:

int SelectedCount

bool IsSelectionFull

int RemainingSelectionCount

bool HasSelection

This makes it easy to integrate the control into forms and validation workflows.

---

Roadmap

• Country service
• CountryPickerView
• PhoneEntryView
• CountryPickerButtonView
• DialCodePickerView
• CountryAutoCompleteView
• CountryFlagView
• CountryCardView
• CountryMultiPickerView
• Built-in PNG country flags
• Image / Emoji flag modes
• Dark / Light / System themes
• Geolocation
• Favorites & recent countries
• Custom country templates
• CountryPickerField
• PhoneNumberView
• CountryDisplayView
• RegionPickerView
• Popup / BottomSheet presentation
• Extended automated tests

---

Supported Frameworks

Framework	Status
.NET 10 MAUI	✅ Supported
.NET 9 MAUI	✅ Supported
.NET 8 MAUI	⚠️ Legacy / no longer actively supported

---

🤝 Contributing

Contributions are welcome.

• Repository: https://github.com/Belagol/Akeng.CountryPicker
• Issues: https://github.com/Belagol/Akeng.CountryPicker/issues
• Pull Requests: https://github.com/Belagol/Akeng.CountryPicker/pulls

---

License

MIT License

---

Made with ❤️ by Dr. Ange Gabriel Belinga using .NET MAUI