CountryPicker.Blazor 1.2.0

CountryPicker.Blazor

A lightweight, high-performance, and beautifully styled Country, State, and City Picker component library for Blazor (Interactive Server & WebAssembly).

🌟 Features

• Zero-Asset Flag Emojis: Leverages standard Unicode regional indicator sequences to display native emoji flags. No external image assets or font files required!
• Searchable Dropdowns: Built-in, high-speed client-side filtering matching by country name, ISO-3166 codes, or phone dialing codes.
• Favorites / Grouping: Pin important or frequently used countries (e.g., ["US", "GB", "GR", "CA", "AU"]) to a dedicated "Favorites" section at the top of the list.
• Cascading Geography: Composed of three complementary components—CountryPicker, StatePicker, and CityPicker—which cascade seamlessly. When a parent country/state changes, child components automatically reset their values.
• Dialing Codes Support: Toggle international phone dial codes (e.g., +1, +30, +44) directly in the select triggers and list items.
• Exclusion & Inclusion Filters: Specify which countries to explicitly exclude/hide or provide a strict list of allowed country codes.
• 🎨 Custom Visual Themes: Out-of-the-box support for four rich visual themes: Light, Dark, Blue, and Forest built on clean CSS variable cascading.
• 📐 Corner Roundness Options: Easily configure custom container and select button corner radius shapes: None, Small, Medium, Large, or Full pills.
• 🗺️ Toggleable Geography Icons: Hide or display helper map (🗺️) and city (🏙️) icons in the triggers and dropdown list items.
• Modern UI & Smooth Animations: Out-of-the-box CSS isolation ensures beautiful, native-feeling panels with micro-interactions, popover animations, clear buttons, and click-outside dismissal (via full-viewport backdrop overlays).
• Interactive Focus: Automatically shifts focus to the search query input as soon as the popover dropdown opens.

🚀 Getting Started

1. Installation

Install the package via the NuGet Package Manager Console:

dotnet add package CountryPicker.Blazor

Note: CountryPicker.Blazor depends on the GeoLocation.Data package for its country/state/city dataset and GeoLocationService. It is pulled in automatically as a transitive dependency when you install CountryPicker.Blazor, so no separate install step is required.

2. Register Services

Register the GeoLocationService (provided by GeoLocation.Data) in your application container (usually inside Program.cs):

using GeoLocation.Data;

// Register the country/state/city geography service
builder.Services.AddSingleton<GeoLocationService>();

3. Add Imports

Add the namespaces to your global imports in _Imports.razor:

@using CountryPicker.Blazor
@using GeoLocation.Data

💻 Usage Examples

Styled Country Picker (Dark Theme & Large Roundness)

Use the <CountryPicker> component with two-way binding on the @bind-Value attribute, and custom style enums:

@page "/simple-picker"
@rendermode InteractiveServer

<h3>Select your Country</h3>

<CountryPicker 
    @bind-Value="SelectedCountry" 
    ShowPhoneCode="true" 
    ShowSearch="true"
    Theme="PickerTheme.Dark"
    Roundness="PickerRoundness.Large"
    Placeholder="Search country records..."
    ButtonPlaceholder="Select your country..." />

@if (SelectedCountry != null)
{
    <p>Selected: <strong>@SelectedCountry.Name</strong> (Code: @SelectedCountry.CountryCode, Phone: +@SelectedCountry.PhoneCode)</p>
}

@code {
    private Country? SelectedCountry { get; set; }
}

Cascading Geography (Country ➔ State ➔ City) with Forest Theme

Implement cascading dropdowns easily by linking parent values to child input parameters. State and City options will load dynamically and clear automatically if parent bindings change.

@page "/cascading-picker"
@rendermode InteractiveServer

<div class="form-group">
    <label>Country:</label>
    <CountryPicker 
        @bind-Value="ActiveCountry"
        FavoriteCountries='new[] { "US", "GB", "CA" }'
        Theme="PickerTheme.Forest"
        Roundness="PickerRoundness.Medium"
        Placeholder="Search country..."
        ButtonPlaceholder="Select Country" />
</div>

<div class="form-group mt-3">
    <label>State / Province:</label>
    <StatePicker 
        @bind-Value="ActiveState"
        CountryCode="@ActiveCountry?.CountryCode"
        Theme="PickerTheme.Forest"
        Roundness="PickerRoundness.Medium"
        ShowIcon="true"
        Placeholder="Search state..."
        ButtonPlaceholder="Select State" />
</div>

<div class="form-group mt-3">
    <label>City:</label>
    <CityPicker 
        @bind-Value="ActiveCity"
        CountryCode="@ActiveCountry?.CountryCode"
        StateId="@ActiveState?.Id"
        Theme="PickerTheme.Forest"
        Roundness="PickerRoundness.Medium"
        ShowIcon="true"
        Placeholder="Search city..."
        ButtonPlaceholder="Select City" />
</div>

@code {
    private Country? ActiveCountry { get; set; }
    private State? ActiveState { get; set; }
    private City? ActiveCity { get; set; }
}

⚙️ Component API Reference

<CountryPicker>

<StatePicker>

<CityPicker>

🛠️ Service APIs

If you need to query geographic data programmatically outside of the UI components, you can inject and use GeoLocationService (from the GeoLocation.Data package) directly in your code.

GeoLocationService

Provides access to the raw database of over 240+ countries and their states/cities.

• GetAll(): Returns all configured countries alphabetically sorted.
• GetByCountryCode(string countryCode): Looks up a country by its 2-letter ISO code (case-insensitive).
• GetByPhoneCode(string phoneCode): Finds all countries matching an international phone code.
• GetStates(string countryCode): Retrieves states/provinces for a given 2-letter country code.
• GetCities(string countryCode, int stateId): Retrieves cities for a given country code and state ID.

See the GeoLocation.Data package documentation for full details on the underlying dataset and models.

🎨 Styles & Customization

The components use modern Blazor CSS Isolation, which means all styles are fully isolated to the CountryPicker.Blazor library and won't leak or conflict with your host application styles.

Using CSS Variables

Our styling engine utilizes CSS Custom Properties (--cp-*) cascading down from the .country-picker-container root. If you want custom visual properties not covered by the enums, you can override variables in your global app stylesheet:

/* Overriding CSS Custom Properties globally */
.country-picker-container {
    --cp-accent: #ff4081 !important; /* Change active focus/borders to hot pink */
    --cp-font: 'Consolas', monospace !important; /* Custom font family override */
    max-width: 100% !important; /* Allow full-width layouts */
}

Available CSS variables to override:

• --cp-bg: Component background colors
• --cp-trigger-bg: Select button background
• --cp-text: Primary text color
• --cp-text-muted: Placeholder/arrow icons
• --cp-border: Form boundary borders
• --cp-accent: Highlight / Focus boundaries
• --cp-dropdown-bg: Popover container background
• --cp-radius: Border radius corners

📄 License & Attribution

This library is licensed under the MIT License.