# Flag
**Also known as:** Country, CountryFlag
## Description
BitFlag renders the flag of a country, named by a BitCountry, an ISO 3166-1 code, a dialing code or an English name. It draws the packaged image, a flat or shiny image set of Bit.BlazorUI.Assets, the Unicode emoji or an image of the page's own, in a frame that carries the size and the shape. It is decorative to assistive technologies until named, and OnClick makes it a keyboard-operable button.
## Parameters
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Alt | `string?` | null | The accessible name of the flag. Without one the flag is decorative; with OnClick it names the button, so say what the click does. |
| AspectRatio | `string?` | null | The aspect ratio of the frame, as any CSS aspect-ratio value (e.g. "4/3"). The height stays and the width follows - the other way round where only a Width is given. A packaged or ImageSet flag is cropped to fill it ("1" draws a square flag) unless a Fit other than Cover is set. |
| AutoAlt | `bool` | false | Names the flag to assistive technologies with the full name of the country it resolved to. An Alt of the page's own wins over it. |
| AutoTitle | `bool` | false | Sets the tooltip of the flag to the full name of the country it resolved to. A Title of the page's own wins over it. |
| Bordered | `bool` | false | Draws a hairline border inside the frame, which keeps a mostly white flag visible on a white surface. |
| Circular | `bool` | false | Clips the flag into a circle. It wins over Rounded where both are set. |
| Classes | `BitFlagClassStyles?` | null | Custom CSS classes for different parts of the flag. |
| Code | `string?` | null | The dialing code of the country, read like a phone number ("+31", "0031", "31"). A shared code resolves to the country owning it ("1" is the United States), so prefer an ISO code where that matters. |
| Country | `BitCountry?` | null | The country of the flag, taken as given rather than looked up. A country of the page's own works too, and one the packaged images do not cover (the European Union) is drawn by a Src or SrcPattern. It wins over Iso2, Iso3, Code and Name. |
| Emoji | `bool` | false | Renders the Unicode emoji flag instead of an image: no request, crisp at any size, but drawn by the platform (Windows draws the two letters of the code). It wins over Src, SrcPattern and ImageSet. |
| FallbackTemplate | `RenderFragment?` | null | What to render when there is no flag to draw: an unknown country, or an image that failed after the packaged flag stood in for it. |
| Fit | `BitImageFit?` | null | How the image fits a frame of another shape (a Src, SrcPattern or AspectRatio). Unset, it covers the frame and is cropped - a packaged or ImageSet flag to the flag inside its image. |
| Grayscale | `bool` | false | Draws the flag in shades of grey, for a country that is not in play. |
| Height | `string?` | null | The height of the flag, as any CSS length; also the width where no Width is set, and the emoji's size. It wins over Size. |
| ImageAttributes | `Dictionary<string, object>` | new Dictionary<string, object>() | Additional HTML attributes for the img element rather than the frame, e.g. a crossorigin or referrerpolicy for a CDN. The flag's own src, alt and loading win. A srcset given here only goes with a Src or SrcPattern; it is dropped for the packaged flag and for an ImageSet, which picks its own srcset. |
| ImageSet | `BitFlagImageSet?` | null | Draws the flag from the flat or shiny set of the Bit.BlazorUI.Assets package (16-64px), at the size the flag and the screen density need - read off Width/Height in px or rem, else Size. Also taken from a CascadingValue of a BitFlagImageSet. Emoji, Src and SrcPattern win over it. |
| ImageSize | `BitFlagImageSize?` | null | Pins the ImageSet image to one size instead of letting the browser pick; it is still scaled to the frame. Only applies with an ImageSet. |
| Iso2 | `string?` | null | The ISO 3166-1 alpha-2 code of the country, case insensitive; "UK" is answered with the United Kingdom ("GB"). An unknown code draws nothing rather than a broken image. |
| Iso3 | `string?` | null | The ISO 3166-1 alpha-3 code of the country, matched case insensitively. |
| Loading | `BitImageLoading?` | null | How the browser loads the flag image. Lazy unless set. |
| Name | `string?` | null | The full English name of the country, case insensitive. Everyday names and abbreviations ("Czechia", "Holland", "USA") resolve too, ignoring accents and punctuation. |
| OnClick | `EventCallback<MouseEventArgs>` | | The callback for when the flag is clicked. It makes the flag a button: in the tab order, activated by Enter and Space, with a 24px pointer target, named by its Alt or else its country. |
| OnError | `EventCallback` | | The callback for when the flag image fails to load; fired again if the packaged flag standing in for a failed Src fails too. |
| OnLoad | `EventCallback` | | The callback for when the flag image has loaded. Never fired for an emoji flag. |
| Rounded | `bool` | false | Rounds the corners of the flag with the theme's surface radius, kept in proportion to the flag's size (--bit-Flag-radius overrides it). Circular wins over it where both are set. |
| Shadow | `bool` | false | Draws the card shadow of the theme under the flag. |
| Size | `BitSize?` | null | The size of the flag, out of the theme's icon sizes; unset, it is --bit-Flag-size, else Medium (16px). Width and Height win over it. |
| Src | `string?` | null | The url of an image of the page's own to draw instead of the packaged flag. A failed one falls back to the packaged flag, then to the FallbackTemplate. It wins over SrcPattern and ImageSet; Emoji wins over it. |
| SrcPattern | `string?` | null | The url of the image of every country, with {iso2}/{iso3} (lower case) or {ISO2}/{ISO3} (upper case) written in - e.g. "https://flagcdn.com/{iso2}.svg". Falls back like a Src; Src and Emoji win over it, and it wins over ImageSet. |
| Styles | `BitFlagClassStyles?` | null | Custom CSS styles for different parts of the flag. |
| Title | `string?` | null | The tooltip of the flag. It is not an accessible name, so a flag that must be named wants an Alt as well. |
| Width | `string?` | null | The width of the flag, as any CSS length. A Height alone usually sets both; with a Height that is not a square, a packaged or ImageSet flag is cropped to fill the frame. It wins over Size. |
| 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 |
| :--- | :--- | :------------ | :---------- |
| FocusAsync | `ValueTask` | | Gives focus to the flag element. Only a flag the browser can focus takes it: one with an OnClick handler, or one given a TabIndex of its own. |
| FocusAsync(bool preventScroll) | `ValueTask` | | Gives focus to the flag element, leaving the page scrolled where it is instead of bringing the flag into view. |
| 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
### BitSize Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Small | 0 | The small size. |
| Medium | 1 | The medium size. |
| Large | 2 | The large size. |
### BitFlagImageSet Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Flat | 0 | The flat artwork, in the same style as the packaged 16 pixel image. |
| Shiny | 1 | The shiny artwork, with a gloss and a soft edge over the flag. |
### BitFlagImageSize Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Size16 | 0 | The 16 pixel image. |
| Size24 | 1 | The 24 pixel image. |
| Size32 | 2 | The 32 pixel image. |
| Size48 | 3 | The 48 pixel image. |
| Size64 | 4 | The 64 pixel image. |
### BitImageFit Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| None | 0 | Neither the image nor the frame are scaled. Whatever of the image does not fit is cropped away from the right and the bottom. |
| Center | 1 | The image is not scaled, and is centered within the frame with the overflow cropped. |
| CenterContain | 2 | The image keeps its aspect ratio, is scaled down where needed so that all of it fits, and is centered in the frame. |
| CenterCover | 3 | The image keeps its aspect ratio, is scaled up where needed so that it covers the frame, and is centered in it. |
| Contain | 4 | The image keeps its aspect ratio and is fully contained within the frame. Nothing is cropped, and whatever of the frame it does not reach is left empty. |
| Cover | 5 | The image keeps its aspect ratio and fills the frame, with whatever falls outside it cropped away. This is what a flag with no Fit set does. |
| Fill | 6 | The image is stretched to fill the frame exactly, at the cost of distorting the flag where the two shapes disagree. |
| ScaleDown | 7 | The image is contained within the frame but never scaled up, so one smaller than the frame keeps its natural size. |
### BitImageLoading Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Eager | 0 | Tells the browser to load the image as soon as the img element is processed, which is what a browser does with an img that has no loading attribute. |
| Lazy | 1 | Tells the user agent to hold off on loading the image until the browser estimates that it will be needed imminently. |
### 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
### BitCountries Properties
The table of countries the flag images and the country lookups of the library are built on. Every country is a shared BitCountry instance named after itself, so it can be written straight into markup, and the lookups below resolve any of the ways one is written down back to it - out of a dictionary rather than by scanning the table.
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| All | `BitCountry[]` | | Every country the packaged flag images cover, in alphabetical order. |
| FindByIso2(string? iso2) | `BitCountry?` | | The country carrying the ISO 3166-1 alpha-2 code, case insensitively and ignoring surrounding whitespace. "UK" is answered with the United Kingdom, whose own code is "GB". |
| FindByIso3(string? iso3) | `BitCountry?` | | The country carrying the ISO 3166-1 alpha-3 code, case insensitively. |
| FindByName(string? name) | `BitCountry?` | | The country carrying the English name, matched against the whole name rather than part of it. The alternative names and abbreviations a country is as widely known by are answered too, and the accents, punctuation and spacing another source spells it with are ignored. |
| FindByCode(string? code) | `BitCountry?` | | The country carrying the dialing code, read the way a telephone number is written: "+31", "00 31" and "31" all reach the Netherlands. A shared code resolves to the country with the highest Priority ("1" is the United States, "7" Russia), else the first alphabetically. |
| Find(string? value) | `BitCountry?` | | The country a single value stands for, read as an alpha-2 code, an alpha-3 code, a name and a dialing code in that order. |
| HasFlag(string? iso2) | `bool` | | Whether a packaged flag image ships for the given alpha-2 code, answered without asking the network for it. |
| GetEmoji(string? iso2) | `string?` | | The Unicode emoji flag of the given alpha-2 code, built from the pair of regional indicator symbols its letters stand for rather than looked up - so it answers for codes the packaged images do not cover, and for "GB-ENG", "GB-SCT" and "GB-WLS". |
### BitCountry Properties
Represents the basic information of a specific country. BitCountries holds one shared instance per country - build a new one rather than editing it - and its Find methods resolve its Name, Code, Iso2 or Iso3 back to it.
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Name | `string` | | The full name of the country. |
| Code | `string` | | The dialing code of the country, written without its leading plus sign. It is not unique: Canada and the United States both carry "1". |
| Iso2 | `string` | | The ISO 3166-1 alpha-2 code of the country, which is what the flag image and the emoji flag are keyed by. |
| Iso3 | `string` | | The ISO 3166-1 alpha-3 code of the country. |
| Priority | `int` | 0 | The tie-breaker among the countries sharing a dialing code; the higher one wins (the United States over Canada for "1"). |
| ExtraCodes | `string[]?` | null | The other dialing codes the country answers to beyond Code (the Dominican Republic's "1-829" and "1-849" beside its "1-809"). |
| DigitsCode | `string` | | The Code reduced to its digits, as it appears in an E.164 number. |
| DigitsCodes | `string[]` | | Every dialing code of the country - Code first, then ExtraCodes - reduced to its digits. |
| Emoji | `string?` | | The flag of the country as a Unicode emoji, built from the pair of regional indicator symbols its Iso2 stands for. Null where the Iso2 is not two ASCII letters. |
### BitFlagClassStyles Properties
Custom CSS classes/styles for the different parts of the BitFlag component.
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Root | `string?` | null | Custom CSS classes/styles for the root element of the flag, which is the frame carrying the size, the shape and the border. |
| Image | `string?` | null | Custom CSS classes/styles for the img element, which is only rendered while the flag is drawn as an image. |
| Emoji | `string?` | null | Custom CSS classes/styles for the element the emoji flag is written in. |
| Fallback | `string?` | null | Custom CSS classes/styles for the element wrapping the FallbackTemplate. |
## 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-Flag-size` | --bit-siz-icon-md | Size of a flag with no Size, Width or Height - also the size the emoji is drawn at. |
| `--bit-Flag-radius` | min(--bit-shp-radius-surface, 1/8 of the size) | Corner radius of a Rounded flag. The default is capped so a theme's large card corner does not turn a small flag into a pill; a value set here is taken as given. |
| `--bit-Flag-border-width` | --bit-shp-brd-width | Border width of a Bordered flag. |
| `--bit-Flag-border-color` | --bit-clr-brd-sec | Border color of a Bordered flag. |
| `--bit-Flag-shadow` | --bit-shd-card | Elevation of a Shadow flag. |
| `--bit-Flag-grayscale-filter` | grayscale(1) | Filter of a Grayscale flag, e.g. grayscale(1) opacity(0.5). |
| `--bit-Flag-hover-opacity` | 0.8 | Opacity of a clickable flag under the pointer. |
| `--bit-Flag-active-opacity` | 0.6 | Opacity of a clickable flag while pressed. |
| `--bit-Flag-focus-color` | --bit-clr-pri-focus | Color of the keyboard focus ring. 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-Flag-emoji-font-family` | 'Apple Color Emoji', 'Segoe UI Emoji', 'Noto Color Emoji', 'Segoe UI Symbol', sans-serif | Font stack of the Emoji flag. Put a flag emoji font of the page's own first to draw flags where the platform draws letters (Windows). |
## Examples
\n**Basic**:
```razor
```
\n**Src, SrcPattern & FallbackTemplate**:
```razor
?
```
```csharp
// A vector image of the flag, inline so the example carries its own file.
private const string japanSvg = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 900 600'%3E%3Crect width='900' height='600' fill='%23fff'/%3E%3Ccircle cx='450' cy='300' r='180' fill='%23bc002d'/%3E%3C/svg%3E";
// One url for every country: {iso2} is written in as the lower-cased alpha-2 code.
private const string flagCdnPattern = "https://flagcdn.com/{iso2}.svg";
// A country the table does not carry: the European Union has an alpha-2 code but no alpha-3 one.
private static readonly BitCountry europeanUnion = new("European Union", "", "EU", "");
```
\n**Aspect ratio & fit**:
```razor
@(eventFlagsRenderCount == 0 ? "Render the flags" : "Render the flags again")
@if (eventFlagsRenderCount > 0)
{
```
```csharp
private readonly BitFlagParams[] flagParams =
[
new()
{
Height = "2rem",
Rounded = true,
Bordered = true,
AutoAlt = true,
AutoTitle = true,
ImageSet = BitFlagImageSet.Shiny,
}
];
```
\n**Size**:
```razor
?
Selected: @(selectedCountry?.Name ?? "(none)")
```
```csharp
private static readonly BitCountry[] clickableCountries =
[
BitCountries.France,
BitCountries.Germany,
BitCountries.Italy,
BitCountries.Spain
];
private BitCountry? selectedCountry;
```
\n**All countries**:
```razor
@foreach (var country in BitCountries.All)
{
```
\n**Cascading parameters**:
```razor