Skip to content
BlazorUI

Extras

CountryPicker

Bit.BlazorUI.ExtrasCountrySelectorCountrySelect

BitCountryPicker picks a country out of a searchable list that shows the flag and the name of each one - for the billing country, the nationality or the country of residence a form asks for. Value is the selected BitCountry; the list can be replaced, trimmed and reordered, searched by name or ISO code, and the whole field is keyboard and screen-reader operable.

Notes

To use this component, you need to install the Bit.BlazorUI.Extras(opens in a new tab) nuget package, as described in the Optional steps of the Getting started page.

Usage

Every example is live. Open its code to see exactly what produced the component running underneath.

Basic

The field opens a list of every country of BitCountries.All, each with its flag and name. Placeholder fills the field while no country is selected.

Label & description

Label (or LabelTemplate) names the field and its list; a click on it moves the focus to the field. Required adds the asterisk and aria-required. Description (or DescriptionTemplate) writes a hint under the field, tied to it through aria-describedby.

Where you have lived for the last six months.

Binding

Value is the selected BitCountry and is two-way bindable, so everything a country carries - its name, its ISO codes, its emoji flag - is at hand the moment it is picked.

Name:
Iso2:
Iso3:
Emoji:

DefaultValue & DefaultCountry

An unbound picker starts on DefaultValue, and OnChange reports what is picked after it. DefaultCountry does the same when no DefaultValue is given - it is the one a cascade hands every picker under it as the market of the app. A bound Value is left as it is by both.

Changed to:

Custom countries

Countries replaces the built-in list (BitCountries.All) and ExcludeCountries trims it.

Preferred countries

PreferredCountries pins countries to the top of the list, set apart from the rest by a rule.

Search box

The search matches names (accents folded, word starts, so united s finds the United States) and ISO codes (de, deu), and the result count is announced to screen readers. Typing on the closed field opens it with the search already started. SearchBoxPlaceholder, SearchBoxAriaLabel and NoResultsMessage set its texts. NoSearchBox removes it; the field then answers to type-ahead, open or closed.

Flags

NoFlags leaves the flags out of the field and the list, and FlagUrlSelector serves them from your own source (returning null keeps the built-in one).

Templates

ValueTemplate renders the content of the field from the selected country, ItemTemplate each row, and NoResultsTemplate the empty result.

Validation

Inside an EditForm the data annotations validate the bound country and the field gets aria-invalid; NoValidate opts out. Outside a form, Invalid marks the field and ErrorMessage (or ErrorMessageTemplate) also writes the reason under it, referenced by aria-describedby and announced when it appears.

We do not ship there yet.
We ship to the European Union only.
We do not ship there yet.​


Disabled & ReadOnly

Disabled dims the field and takes it out of the tab order. ReadOnly keeps it focusable and its country readable while refusing to open the list; the field drops its caret.

Variants

NoBorder removes the frame, and Underlined keeps only a bottom rule that thickens on focus. Background and Border take the fill and the frame from the neutral color kinds, for a field on a surface other than the primary one.


Callout

DropDirection (TopAndBottom by default, or All) and MaxHeight place and size the list. The arrow keys wrap at its ends unless NoWrapNavigation is set; Home, End, Page Up and Page Down move through it too, and Escape or Alt+Up close it. Responsive turns it into a full-height side panel on small screens, with the Label and a close button (ResponsiveCloseIconName, ResponsiveCloseButtonAriaLabel) - narrow the window to see it.

Events

OnChange reports the picked country, OnOpen / OnClose follow the list, OnSearch reports the search term, and OnFocus / OnBlur follow the field.

Selected country:
Search text:
Callout: closed
Field: blurred

Programmatic control

IsOpen is two-way bindable, and a reference offers OpenAsync, CloseAsync, SelectCountryAsync (which raises the same events picking it in the list does) and FocusAsync.



IsOpen: False

Form submission

For a plain HTML form, Name posts the ISO 3166-1 alpha-2 code of the selected country through a hidden field.

Posted as country:

Localization

Every text the picker shows or announces can be translated. Country names come from Countries; the search box and the empty result take SearchBoxPlaceholder, SearchBoxAriaLabel and NoResultsMessage; and SearchResultsAnnouncement phrases the result count a screen reader hears.

Cascading parameters

BitParams hands a BitCountryPickerParams to every country picker under it - the app's market, country list, look and translated texts, set once. The visitor's own country is BitCountries.FindByIso2(RegionInfo.CurrentRegion.TwoLetterISORegionName). A picker keeps any parameter it sets itself. What belongs to one field only (Value, DefaultValue, IsOpen, Name, Invalid, ErrorMessage and the events) is not cascaded.


Color

Color paints the frame and the focus ring in one of the general colors - a semantic one or a neutral family. A Border kind, when set, takes the frame back and leaves Color the ring.

External Icons

ResponsiveCloseIcon takes the icon of the close button of the responsive panel from any CSS-class based library (FontAwesome, Bootstrap Icons) as raw classes or through the BitIconInfo helpers, and wins over ResponsiveCloseIconName. Reference the library's stylesheet in your app, and narrow the window to see it.

Size

Size scales the height, padding, text, flags and list rows together.

Style & Class

The public --bit-CountryPicker-* custom properties (see the CSS variables table) re-skin the field without a selector: on :root for the whole app, on an ancestor for the pickers inside it, or in one picker's Style. The country list is moved to the end of the body while it is open, yet it keeps inheriting from the field and every ancestor of it, so a variable set in any of those places re-skins the list as well. They restyle the default, not a choice: an explicit Color, Background, Border or Size wins over the variables for what it sets. Style and Class reach the root, Styles and Classes every part by name.

CSS variables on one picker (open its list too):

CSS variables on an ancestor (open its list too):

Style, Class, Styles and Classes:

RTL

Dir="BitDir.Rtl" mirrors the field, the callout and the responsive panel.

CSS variables

The public custom properties this component reads off its root, for what no parameter covers.

Every variable is read with a fallback and never declared by the component, so it inherits like any other custom property: set one on :root (or in a [bit-theme] block) to restyle every instance, on any ancestor to restyle the ones inside it, or on the Style of one instance to restyle it - and any instance nested inside it, which inherits the value too; a parameter changes one alone, as does the real CSS property on the instance's Style / Styles when that property does not inherit (opacity: 1 keeps one disabled instance undimmed without undimming a disabled one inside it), while an inherited one such as color or font-family also reaches the nested instances that do not set it themselves. Leave a variable unset and the component falls back to the theme token beside it.

BitCountryPicker CSS variables

Name Default value Description
--bit-CountryPicker-background --bit-clr-bg-pri Fill of the field. The Background parameter wins over it.
--bit-CountryPicker-color --bit-clr-fg-pri Name of the selected country in the field.
--bit-CountryPicker-placeholder-color --bit-clr-fg-sec Placeholder of the field and of the search box.
--bit-CountryPicker-border-color --bit-clr-brd-pri Frame at rest. The Border and Color parameters win over it.
--bit-CountryPicker-hover-border-color --bit-clr-brd-pri-hover Frame under a pointer, on devices that can hover. The Border and Color parameters win over it.
--bit-CountryPicker-border-width --bit-shp-brd-width Thickness of the frame.
--bit-CountryPicker-radius --bit-shp-radius-control Corner radius of the frame.
--bit-CountryPicker-min-height --bit-siz-ctrl-md Smallest height of the frame. The Size parameter wins over it.
--bit-CountryPicker-font-size --bit-tpg-fs-sm Text size of the field and of the country list. The Size parameter wins over it.
--bit-CountryPicker-padding 0 --bit-siz-ctrl-pad-x-md Padding of the field. The Size parameter wins over it.
--bit-CountryPicker-focus-color --bit-clr-pri-focus Focused frame and focus ring, and the keyboard cues of the active row and the close button of the list. The Color parameter wins over it. While it is unset, the focus ring is the library's own --bit-shd-focus-ring, so replacing that token re-shapes it too.
--bit-CountryPicker-invalid-color --bit-clr-err / --bit-clr-err-focus Frame, focus ring and error message of a rejected value.
--bit-CountryPicker-disabled-color --bit-clr-fg-dis Text and glyphs when disabled.
--bit-CountryPicker-disabled-background --bit-clr-bg-dis Fill when disabled.
--bit-CountryPicker-disabled-border-color --bit-clr-brd-dis Frame when disabled.
--bit-CountryPicker-caret-color --bit-clr-fg-sec The caret of the field.
--bit-CountryPicker-flag-size --bit-siz-icon-md Flags of the field and of the list. The Size parameter wins over it.
--bit-CountryPicker-flag-radius --bit-shp-radius-none Corner radius of a flag.
--bit-CountryPicker-label-color --bit-clr-fg-pri Label text.
--bit-CountryPicker-label-font-size --bit-CountryPicker-font-size Label text size. The Size parameter wins over it.
--bit-CountryPicker-label-font-weight --bit-tpg-field-label-font-weight Label weight.
--bit-CountryPicker-required-color --bit-clr-req The asterisk of a Required field.
--bit-CountryPicker-description-color --bit-clr-fg-sec Description text.
--bit-CountryPicker-footer-font-size --bit-tpg-fs-2xs Text size of the description and of the error message.
--bit-CountryPicker-callout-background --bit-clr-bg-pri The surface of the country list.
--bit-CountryPicker-callout-border-color --bit-clr-brd-pri Border of the country list, and the rules under its search box and under the preferred countries.
--bit-CountryPicker-callout-radius --bit-shp-radius-popup Corner radius of the country list.
--bit-CountryPicker-callout-shadow --bit-shd-popup (--bit-shd-sheet for the responsive panel) Elevation of the country list.
--bit-CountryPicker-callout-max-height --bit-siz-popup-max-height Tallest the scrolling list grows. The MaxHeight parameter wins over it.
--bit-CountryPicker-responsive-width spacing(34) Width of the side panel a Responsive picker opens on a small screen.
--bit-CountryPicker-overlay-background transparent The layer behind an open list; give it a color for a modal-style scrim.
--bit-CountryPicker-item-height --bit-siz-item-md Smallest height of a row of the list. The Size parameter wins over it.
--bit-CountryPicker-item-color --bit-clr-fg-pri Country name of a row, and the text of the search box.
--bit-CountryPicker-item-hover-background --bit-clr-bg-pri-hover Row under the pointer, and the row the arrow keys are on.
--bit-CountryPicker-item-selected-background --bit-clr-bg-sec The selected row.
--bit-CountryPicker-item-selected-color --bit-CountryPicker-item-color Text of the selected row.

API

Every parameter, public member, sub-class and enum this component exposes.

BitCountryPicker parameters

Name Type Default value Description
Background BitColorKind? null The color kind of the fill of the country picker. An explicit value wins over --bit-CountryPicker-background; left unset, the fill is the primary kind unless it says otherwise.
Border BitColorKind? null The color kind of the frame of the country picker, winning over the main color of Color (which keeps the focus ring). An explicit value wins over --bit-CountryPicker-border-color and --bit-CountryPicker-hover-border-color; left unset, the frame is the primary border unless an explicit Color or those variables say otherwise.
Classes BitCountryPickerClassStyles? null Custom CSS classes for different parts of the BitCountryPicker.
Color BitColor? null The general color of the country picker: the frame takes its main color and the focus ring its focus color. An explicit value wins over --bit-CountryPicker-focus-color and the --bit-CountryPicker-* border colors (an explicit Border still wins the frame); left unset, the field is primary unless those variables say otherwise.
Countries ICollection<BitCountry> BitCountries.All The list of the countries the picker offers.
DefaultCountry BitCountry? null The country an unbound picker starts on when no DefaultValue is given - the market of an app, which a BitCountryPickerParams can hand every picker under it. A bound Value is left as it is. It is matched to the list by its ISO code, so the picker starts on the country the list offers (with the name it shows), and on none when the list does not offer it.
Description string? null The description shown under the country picker, tied to the field through aria-describedby.
DescriptionTemplate RenderFragment? null The custom template for the description of the country picker.
DropDirection BitDropDirection BitDropDirection.TopAndBottom Determines the allowed drop directions of the country list callout.
ErrorMessage string? null The error message shown under the country picker, which also puts the field in its invalid state. It is referenced through aria-describedby and announced when it appears.
ErrorMessageTemplate RenderFragment? null The custom template for the error message of the country picker, putting the field in the same invalid state.
ExcludeCountries ICollection<BitCountry>? null The countries to leave out of the list, which is how a list built from Countries is trimmed without being written out in full.
FlagUrlSelector Func<BitCountry, string?>? null The url of the flag image of a country, replacing the flags that ship with the library. Returning null or an empty string leaves that country with the built-in flag.
Invalid bool false Renders the country picker in an invalid state without going through the validation of an EditContext.
IsOpen bool false Determines the opening state of the country list callout. (two-way bound)
ItemTemplate RenderFragment<BitCountry>? null The custom template for each country of the list.
Label string? null The label of the country picker shown above the field, which is also the accessible name of the field and of the country list.
LabelTemplate RenderFragment? null The custom template for the label of the country picker.
MaxHeight int? null The maximum height of the country list callout in pixels.
NoBorder bool false Removes the border of the country picker.
NoFlags bool false Hides the flag images of the countries in the field and in the list.
NoResultsMessage string? null The message to show, and to announce, when the search result of the country list is empty.
NoResultsTemplate RenderFragment? null The custom template to show when the search result of the country list is empty.
NoSearchBox bool false Hides the search box of the country list. The field then answers to type-ahead instead, open or closed.
NoWrapNavigation bool false Stops the keyboard navigation of the country list from wrapping around at its two ends.
OnBlur EventCallback<FocusEventArgs> The callback that is invoked when the field loses focus.
OnClose EventCallback The callback that is invoked when the country list callout closes.
OnFocus EventCallback<FocusEventArgs> The callback that is invoked when the field receives focus.
OnOpen EventCallback The callback that is invoked when the country list callout opens.
OnSearch EventCallback<string?> The callback that is invoked when the search text of the country list changes.
Placeholder string? null The text shown in the field while no country is selected.
PreferredCountries ICollection<BitCountry>? null The countries to pin to the top of the list, set apart from the rest of it by a rule.
Responsive bool false Shows the country list as a full height panel on small screens instead of an inline callout.
ResponsiveCloseButtonAriaLabel string? null The aria-label of the close button of the responsive panel of the country list.
ResponsiveCloseIcon BitIconInfo? null The icon of the close button of the responsive panel. Takes precedence over ResponsiveCloseIconName when both are set, and renders icons from external libraries like FontAwesome or Bootstrap Icons.
ResponsiveCloseIconName string? null The icon name of the close button of the responsive panel from the Fluent UI icon set.
SearchBoxAriaLabel string? null The aria-label of the search box of the country list. Falls back to the search box placeholder, then to a default English value.
SearchBoxPlaceholder string? null The placeholder text of the search box of the country list.
SearchResultsAnnouncement Func<int, string?>? null What a screen reader announces for the number of countries a search term leaves in the list, in place of the default "1 country found" / "{count} countries found". Returning null or an empty string keeps a count from being announced.
Size BitSize? null The size of the country picker. An explicit value wins over the --bit-CountryPicker-* size variables (minimum height, font sizes, padding, flag size, row height); left unset, the field is medium unless those variables say otherwise.
Styles BitCountryPickerClassStyles? null Custom CSS styles for different parts of the BitCountryPicker.
Title string? null The tooltip (title attribute) of the country picker.
Underlined bool false Renders the country picker with only a bottom border instead of a full one.
ValueTemplate RenderFragment<BitCountry?>? null The custom template for the content of the field, receiving the selected country (null while none is).

BitCountryPicker public members

Name Type Default value Description
OpenAsync Task Opens the country list. It does nothing while the field is disabled or read-only.
CloseAsync Task Closes the country list.
SelectCountryAsync Task Selects the given country exactly as picking it in the list would, so the same events fire. The country is matched to the list by its ISO code, and one the list does not offer is not selected.

BitInputBase parameters

Name Type Default value Description
DefaultValue TValue? null The default value of the input to be used in uncontrolled mode (i.e. when the Value is not bound), typically used alongside the OnChange callback.
DisplayName string? null Gets or sets the display name for this field.
InputHtmlAttributes IReadOnlyDictionary<string, object>? null Gets or sets a collection of additional attributes that will be applied to the created element.
Name string? null Gets or sets the name of the element. Allows access by name from the associated form.
NoValidate bool false Disables the validation of the input.
OnChange EventCallback<TValue?> Callback for when the input value changes.
ReadOnly bool false Makes the input read-only.
Required bool false Makes the input required.
Value TValue? null Gets or sets the value of the input. This should be used with two-way binding.

BitInputBase public members

Name Type Default value Description
InputElement ElementReference The ElementReference of the input element.
FocusAsync() () => ValueTask Gives focus to the input element.
FocusAsync(bool preventScroll) (bool preventScroll) => ValueTask Gives focus to the input element.

BitComponentBase parameters

Name Type Default value Description
AriaLabel string? null Gets or sets the accessible label for the component, used by assistive technologies.
Class string? null Gets or sets the CSS class name(s) to apply to the rendered element.
Dir BitDir? null Gets or sets the text directionality for the component's content.
Disabled bool false Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction.
ForceAnimation bool false Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested.
HtmlAttributes Dictionary<string, object> new Dictionary<string, object>() Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. An attribute written on the component wins over an entry of the same name.
Id string? null Gets or sets the unique identifier for the component's root element.
Style string? null Gets or sets the CSS style string to apply to the rendered element.
TabIndex string? null Gets or sets the tab order index for the component when navigating with the keyboard.
Visibility BitVisibility BitVisibility.Visible Gets or sets the visibility state (visible, hidden, or collapsed) of the component.

BitComponentBase public members

Name Type Default value Description
UniqueId Guid Guid.NewGuid() Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed.
RootElement ElementReference Gets the reference to the root HTML element associated with this component.

BitCountryPickerClassStyles properties

Name Type Default value Description
Root string? null Custom CSS classes/styles for the root element of the BitCountryPicker.
Label string? null Custom CSS classes/styles for the label of the BitCountryPicker.
Field string? null Custom CSS classes/styles for the field (the button that opens the country list) of the BitCountryPicker.
Text string? null Custom CSS classes/styles for the content of the field (the flag and the name of the selected country, or the placeholder) of the BitCountryPicker.
Flag string? null Custom CSS classes/styles for the flag image of the countries of the BitCountryPicker.
Caret string? null Custom CSS classes/styles for the caret down element of the field of the BitCountryPicker.
ErrorMessageContainer string? null Custom CSS classes/styles for the container of the error message of the BitCountryPicker.
ErrorMessage string? null Custom CSS classes/styles for the error message of the BitCountryPicker.
DescriptionContainer string? null Custom CSS classes/styles for the container of the description of the BitCountryPicker.
Description string? null Custom CSS classes/styles for the description of the BitCountryPicker.
Overlay string? null Custom CSS classes/styles for the overlay of the country list of the BitCountryPicker.
Callout string? null Custom CSS classes/styles for the callout of the country list of the BitCountryPicker.
SearchBox string? null Custom CSS classes/styles for the search box of the country list of the BitCountryPicker.
ScrollContainer string? null Custom CSS classes/styles for the scroll container of the country list of the BitCountryPicker.
List string? null Custom CSS classes/styles for the list (the listbox element) of the BitCountryPicker.
Item string? null Custom CSS classes/styles for each item of the country list of the BitCountryPicker.
ItemName string? null Custom CSS classes/styles for the name of each item of the country list of the BitCountryPicker.
NoResults string? null Custom CSS classes/styles for the no results message of the country list of the BitCountryPicker.
ResponsiveLabelContainer string? null Custom CSS classes/styles for the label container of the responsive panel of the country list of the BitCountryPicker.
ResponsiveLabel string? null Custom CSS classes/styles for the label of the responsive panel of the country list of the BitCountryPicker.
ResponsiveCloseButton string? null Custom CSS classes/styles for the close button of the responsive panel of the country list of the BitCountryPicker.
ResponsiveCloseIcon string? null Custom CSS classes/styles for the icon of the close button of the responsive panel of the country list of the BitCountryPicker.

BitCountry properties

The basic information of a country. BitCountries holds one shared instance per country.

Name Type Default value Description
Name string The full name of the country.
Code string The dialing code of the country.
Iso2 string The ISO 3166-1 alpha-2 code of the country.
Iso3 string The ISO 3166-1 alpha-3 code of the country.
Priority int 0 The tie-breaking priority of the country among the ones that share its dialing code, where a higher number wins.
ExtraCodes string[]? null The other dialing codes the country answers to beyond Code.
Emoji string? The flag of the country as a Unicode emoji, built from its Iso2.

BitColor enum

Name Value Description
Primary 0 Primary general color.
Secondary 1 Secondary general color.
Tertiary 2 Tertiary general color.
Info 3 Info general color.
Success 4 Success general color.
Warning 5 Warning general color.
SevereWarning 6 SevereWarning general color.
Error 7 Error general color.
PrimaryBackground 8 Primary background color.
SecondaryBackground 9 Secondary background color.
TertiaryBackground 10 Tertiary background color.
PrimaryForeground 11 Primary foreground color.
SecondaryForeground 12 Secondary foreground color.
TertiaryForeground 13 Tertiary foreground color.
PrimaryBorder 14 Primary border color.
SecondaryBorder 15 Secondary border color.
TertiaryBorder 16 Tertiary border color.

BitColorKind enum

Name Value Description
Primary 0 The primary color kind.
Secondary 1 The secondary color kind.
Tertiary 2 The tertiary color kind.
Transparent 3 The transparent color kind.

BitDropDirection enum

Name Value Description
All 0 The direction determined automatically based on the available spaces in all directions.
TopAndBottom 1 The direction determined automatically based on the available spaces in only top and bottom directions.

BitSize enum

Name Value Description
Small 0 The small size.
Medium 1 The medium size.
Large 2 The large size.

BitVisibility enum

Name Value Description
Visible 0 The content of the component is visible.
Hidden 1 The content of the component is hidden, but the space it takes on the page remains (visibility:hidden).
Collapsed 2 The component is hidden (display:none).

BitDir enum

Name Value Description
Ltr 0 Ltr (left to right) is to be used for languages that are written from the left to the right (like English).
Rtl 1 Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic).
Auto 2 Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element.

Feedback

Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.