# CountryPicker
**Also known as:** CountrySelector, CountrySelect
## Description
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.
## 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). |
| 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. |
| 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. |
## 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. |
| 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. |
| 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. |
## Enums
### 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. |
## Sub Classes
### 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. |
## CSS Variables
Public CSS custom properties read off the component's root. Set one on `:root` to restyle every instance, on any ancestor to restyle the ones inside it, or on the `Style` of one instance to restyle it and every instance nested inside it, which inherits the value too - a parameter changes one alone, as does the real CSS property on its `Style` / `Styles` when that property does not inherit (`opacity`); an inherited one (`color`, `font-family`) reaches the nested instances that do not set it themselves.
| 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. |
## Examples
\n**Basic**:
```razor
customCountries =
[
BitCountries.UnitedStates,
BitCountries.Canada,
BitCountries.UnitedKingdom,
BitCountries.Germany,
BitCountries.France,
];
private readonly List excludedCountries =
[
BitCountries.UnitedStates,
BitCountries.UnitedKingdom,
BitCountries.Germany,
];
```
\n**Preferred countries**:
```razor
preferredCountries =
[
BitCountries.Germany,
BitCountries.France,
BitCountries.UnitedStates,
];
```
\n**Search box**:
```razor
@(country is null ? "Pick one" : $"{country.Emoji} {country.Name} ({country.Iso3})")
@country.Emoji
@country.Iso2
🔍 nothing here
```
\n**Validation**:
```razor
Submit
@if (validationSubmitted)
{
Toggle the list
Select Japan
Focus
germanCountries =
[
new("Deutschland", "49", "DE", "DEU"),
new("Frankreich", "33", "FR", "FRA"),
new("Italien", "39", "IT", "ITA"),
new("Österreich", "43", "AT", "AUT"),
new("Schweiz", "41", "CH", "CHE"),
];
```
\n**Cascading parameters**:
```razor
persianCountries =
[
new("ایران", "98", "IR", "IRN"),
new("افغانستان", "93", "AF", "AFG"),
new("ترکیه", "90", "TR", "TUR"),
new("عراق", "964", "IQ", "IRQ"),
new("عمان", "968", "OM", "OMN"),
];
```
Name: @boundCountry?.Name
Iso2: @boundCountry?.Iso2
Iso3: @boundCountry?.Iso3
Emoji: @boundCountry?.Emoji
```
```csharp
private BitCountry? boundCountry;
```
\n**DefaultValue & DefaultCountry**:
```razor
Changed to: @changedCountry?.Name
Submitted: @validationModel.Nationality?.Name
}
```
```csharp
public class BitCountryPickerValidationModel
{
[Required(ErrorMessage = "Select your nationality.")]
public BitCountry? Nationality { get; set; }
}
private bool validationSubmitted;
private readonly BitCountryPickerValidationModel validationModel = new();
```
\n**Disabled & ReadOnly**:
```razor
Selected country: @eventCountry?.Name
Search text: @searchedText
Callout: @calloutState
Field: @focusState
```
```csharp
private BitCountry? eventCountry;
private string? searchedText;
private string calloutState = "closed";
private string focusState = "blurred";
```
\n**Programmatic control**:
```razor
IsOpen: @isCalloutOpen
```
```csharp
private bool isCalloutOpen;
private BitCountryPicker controlledPicker = default!;
```
\n**Form submission**:
```razor
Posted as country: @submissionCountry?.Iso2
```
```csharp
private BitCountry? submissionCountry;
```
\n**Localization**:
```razor