# Badge
## Description
Badge is the small marker that reports what is waiting behind another element: a count capped at a max and hidden at zero, a string, an icon, a template or a plain dot. It anchors to fifteen positions around its child, or sits beside it or on its own in the flow. Given a handler or a URL it becomes a real button or link, and a text alternative and a live region carry what it shows to screen readers.
## Parameters
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Bordered | `bool` | false | Draws a ring around the badge in the color of the page behind it, so it stays legible over a busy child such as an avatar or an image. |
| ChildContent | `RenderFragment?` | null | The content the badge applies to. Without it the badge renders standalone, in the flow of the page. |
| Classes | `BitBadgeClassStyles?` | null | Custom CSS classes for different parts of the BitBadge. |
| Color | `BitColor?` | null | The general color of the badge. An explicit value wins over the --bit-Badge-* color variables; left unset, the badge is primary unless they say otherwise. |
| Content | `object?` | null | Content you want inside the badge. A number is capped by Max and hidden at zero by ShowZero; any other value renders through its ToString(). A badge with nothing to show is not rendered. |
| ContentTemplate | `RenderFragment?` | null | Custom markup rendered in place of Content. Max and ShowZero do not read it, and a Live badge showing one needs a Description to announce. |
| Decorative | `bool` | false | Hides the badge (never its child) from assistive technologies, for a badge whose focusable child already names the count. A Live region keeps announcing, and a button or link badge is never hidden. |
| Description | `string?` | null | Text alternative for assistive technologies (e.g. "5 unread messages"), read in place of the visible content. On a button or link badge named by an AriaLabel it describes the control instead; on a plain dot or icon-only badge the AriaLabel stands in for it, while a badge showing a count keeps saying the count. |
| Dot | `bool` | false | Reduces the size of the badge and hides any of its content. Pair it with a Description. |
| Hidden | `bool` | false | The visibility of the badge. A hidden badge is removed from the DOM while its child content keeps rendering. |
| Href | `string?` | null | Turns the badge into a real link to the URL. While Disabled is true the href is dropped and the badge leaves the tab order. |
| Icon | `BitIconInfo?` | null | Gets or sets the icon to display using custom CSS classes for external icon libraries. Takes precedence over IconName when both are set. |
| IconName | `string?` | null | Gets or sets the name of the icon to display from the built-in Fluent UI icons. |
| Inline | `bool` | false | Lays the badge beside its child content instead of over it. Overlap no longer applies and only the side of Position is read: Start/Left before the child, the rest after. |
| Live | `bool` | false | Announces every change of the badge through a polite live region, including it appearing and disappearing. Reads the Description, or the counter itself. |
| Max | `int?` | null | Caps a numeric Content: above it the badge shows the max followed by a plus (99+) and the real figure as its tooltip, shown wherever the badge takes the pointer (an overlaid one leaves it to its child). |
| OffsetX | `string?` | null | Moves the badge along the horizontal axis by the given CSS length, on top of its Position. A positive value moves the badge to the right in both directions of writing. |
| OffsetY | `string?` | null | Moves the badge along the vertical axis by the given CSS length, on top of its Position. A positive value moves the badge down. |
| OnClick | `EventCallback<MouseEventArgs>` | | Turns the badge into a real, keyboard-operable button. The click does not reach the element underneath. |
| Overlap | `bool` | false | Pulls the badge in over the child content, for a child with a rounded outline such as an avatar. |
| Position | `BitPosition?` | null | The position of the badge. The Left/Right positions are physical, while the Start/End ones follow the direction of writing. |
| Pulse | `bool` | false | Renders an expanding ring around the badge to report that something is in progress. Under reduced motion it stops and stays as a still halo. |
| Rel | `BitLinkRels?` | null | The relationship between the current document and the one the Href of the badge leads to. A badge opening in a new browsing context gets noopener added to it, unless it already says NoOpener, NoReferrer or Opener. |
| Reversed | `bool` | false | Reverses the direction flow of the content of the badge, which puts the icon after the content. |
| Shape | `BitShape?` | null | The corner shape of the badge. Only Pill, Rounded and Square are honoured: a badge takes its box from its own content, so Circle has no proportions to impose and falls back to the default. An explicit value wins over --bit-Badge-radius; left unset, the badge is a pill unless it says otherwise. |
| ShowZero | `bool` | true | Renders the badge when its numeric Content is zero. Turn it off to hide an emptied counter; an icon or a ContentTemplate keeps the badge on the page. |
| Size | `BitSize?` | null | The size of the badge: its height, type size and padding, and the diameter of a dot. An explicit value wins over the --bit-Badge-* size variables; left unset, the badge is medium unless they say otherwise. |
| Styles | `BitBadgeClassStyles?` | null | Custom CSS styles for different parts of the BitBadge. |
| Target | `string?` | null | The browsing context the Href of the badge is opened in, for example _blank. |
| Title | `string?` | null | The tooltip of the badge itself (not of its child). Replaces the real figure a capped count shows on its own. Not a text alternative: use Description for screen readers. An overlaid badge lets the pointer through to its child, so its tooltip shows once it is standalone, inline or clickable. |
| Variant | `BitVariant?` | null | The visual variant of the badge. |
| 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 |
| :--- | :--- | :------------ | :---------- |
| 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. |
### BitSize Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Small | 0 | The small size. |
| Medium | 1 | The medium size. |
| Large | 2 | The large size. |
### BitShape Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Rounded | 0 | The corner radius the current theme gives to this kind of surface, which is what most components draw unless something says otherwise. |
| Square | 1 | Sharp corners with no radius at all, for content that meets its container edge to edge. |
| Pill | 2 | Fully rounded ends, whatever the theme says: a pill where the box is wider than it is tall, and a circle where the box is square. |
| Circle | 3 | A true circle, which takes its diameter from whichever of the height and the width is set rather than leaving the proportions of the box alone. It is the only value that changes the size of what it draws. |
### BitPosition Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| TopLeft | 0 | The top left corner, in both reading directions. |
| TopCenter | 1 | The top edge, centered horizontally. |
| TopRight | 2 | The top right corner, in both reading directions. |
| TopStart | 3 | The top edge, on the side the reading direction starts from. |
| TopEnd | 4 | The top edge, on the side the reading direction ends at. |
| CenterLeft | 5 | The left edge, centered vertically, in both reading directions. |
| Center | 6 | Centered both ways. |
| CenterRight | 7 | The right edge, centered vertically, in both reading directions. |
| CenterStart | 8 | Centered vertically, on the side the reading direction starts from. |
| CenterEnd | 9 | Centered vertically, on the side the reading direction ends at. |
| BottomLeft | 10 | The bottom left corner, in both reading directions. |
| BottomCenter | 11 | The bottom edge, centered horizontally. |
| BottomRight | 12 | The bottom right corner, in both reading directions. |
| BottomStart | 13 | The bottom edge, on the side the reading direction starts from. |
| BottomEnd | 14 | The bottom edge, on the side the reading direction ends at. |
### BitVariant Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Fill | 0 | Fill styled variant. |
| Outline | 1 | Outline styled variant. |
| Text | 2 | Text styled variant. |
### BitLinkRels Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Alternate | 1 | Provides a link to an alternate representation of the document. (i.e. print page, translated or mirror) |
| Author | 2 | Provides a link to the author of the document. |
| Bookmark | 4 | Permanent URL used for bookmarking. |
| External | 8 | Indicates that the referenced document is not part of the same site as the current document. |
| Help | 16 | Provides a link to a help document. |
| License | 32 | Provides a link to licensing information for the document. |
| Next | 64 | Provides a link to the next document in the series. |
| NoFollow | 128 | Links to an unendorsed document, like a paid link. ("NoFollow" is used by Google, to specify that the Google search spider should not follow that link) |
| NoOpener | 256 | Requires that any browsing context created by following the hyperlink must not have an opener browsing context. |
| NoReferrer | 512 | Makes the referrer unknown. No referrer header will be included when the user clicks the hyperlink. |
| Prev | 1024 | The previous document in a selection. |
| Search | 2048 | Links to a search tool for the document. |
| Tag | 4096 | A tag (keyword) for the current document. |
| Me | 8192 | Indicates that the linked document represents the person who owns the current content. (used for identity verification) |
| Opener | 16384 | Requires that any browsing context created by following the hyperlink keeps its opener browsing context. (reverses the implicit noopener modern browsers apply to _blank targets) |
| PrivacyPolicy | 32768 | Links to the privacy policy that applies to the current document. (rendered as privacy-policy) |
| Sponsored | 65536 | Marks the link as an advertisement or paid placement, so search engines do not count it as an organic endorsement. |
| TermsOfService | 131072 | Links to the terms of service that apply to the current document. (rendered as terms-of-service) |
| Ugc | 262144 | Marks the link as user-generated content, like forum posts or comments, for search engines. |
### 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
### BitBadgeClassStyles Properties
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Root | `string?` | null | Custom CSS classes/styles for the root element of the BitBadge. |
| BadgeWrapper | `string?` | null | Custom CSS classes/styles for the badge wrapper of the BitBadge. |
| Badge | `string?` | null | Custom CSS classes/styles for the badge of the BitBadge. |
| Icon | `string?` | null | Custom CSS classes/styles for the icon of the BitBadge. |
| Content | `string?` | null | Custom CSS classes/styles for the content of the BitBadge. |
| Description | `string?` | null | Custom CSS classes/styles for the visually hidden description of the BitBadge. |
| LiveRegion | `string?` | null | Custom CSS classes/styles for the visually hidden live region of the BitBadge, rendered while Live is on and the badge is not a button. |
### BitIconInfo Properties
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Name | `string?` | null | Gets or sets the name of the icon. |
| BaseClass | `string?` | null | Gets or sets the base CSS class for the icon. For built-in Fluent UI icons, this defaults to "bit-icon". For external icon libraries like FontAwesome, you might set this to "fa" or leave empty. |
| Prefix | `string?` | null | Gets or sets the CSS class prefix used before the icon name. For built-in Fluent UI icons, this defaults to "bit-icon--". For external icon libraries, you might set this to "fa-" or leave empty. |
## 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-Badge-color` | Per variant, from the primary role | Text and icon color. In the Outline variant it is also the border color. The Color parameter wins over it. Shared by the three variants: --bit-Badge-fill-color, --bit-Badge-outline-color and --bit-Badge-text-color are read ahead of it. |
| `--bit-Badge-background` | Per variant, from the primary role | Background. In the Fill variant it is also the border color. The Color parameter wins over it in Fill; the transparent background of Outline and Text is its alone. Shared by the three variants: --bit-Badge-fill-background, --bit-Badge-outline-background and --bit-Badge-text-background are read ahead of it. |
| `--bit-Badge-border-color` | The background (Fill), the text color (Outline), transparent (Text) | Border color, in every state. The Color parameter wins over it, except over the transparent border of Text. Shared by the three variants: --bit-Badge-fill-border-color, --bit-Badge-outline-border-color and --bit-Badge-text-border-color are read ahead of it. |
| `--bit-Badge-hover-background` | Per variant, from the primary role | Background of a clickable (OnClick or Href) badge on hover. Set it together with --bit-Badge-background. The Color parameter wins over it. Shared by the three variants: --bit-Badge-fill-hover-background, --bit-Badge-outline-hover-background and --bit-Badge-text-hover-background are read ahead of it. |
| `--bit-Badge-active-background` | Per variant, from the primary role | Background of a clickable badge while pressed. The Color parameter wins over it. Shared by the three variants: --bit-Badge-fill-active-background, --bit-Badge-outline-active-background and --bit-Badge-text-active-background are read ahead of it. |
| `--bit-Badge-fill-color` | --bit-Badge-color | Text and icon color of a Fill badge alone, read ahead of --bit-Badge-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Badge-fill-background` | --bit-Badge-background | Background of a Fill badge alone, read ahead of --bit-Badge-background so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Badge-fill-border-color` | --bit-Badge-border-color | Border color, in every state, of a Fill badge alone, read ahead of --bit-Badge-border-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Badge-fill-hover-background` | --bit-Badge-hover-background | Background on hover of a Fill badge alone, read ahead of --bit-Badge-hover-background so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Badge-fill-active-background` | --bit-Badge-active-background | Background while pressed of a Fill badge alone, read ahead of --bit-Badge-active-background so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Badge-outline-color` | --bit-Badge-color | Text and icon color of an Outline badge alone, read ahead of --bit-Badge-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Badge-outline-background` | --bit-Badge-background | Background of an Outline badge alone, read ahead of --bit-Badge-background so a theme can set this variant apart from the other two. The Color parameter leaves it alone. |
| `--bit-Badge-outline-border-color` | --bit-Badge-border-color | Border color, in every state, of an Outline badge alone, read ahead of --bit-Badge-border-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Badge-outline-hover-background` | --bit-Badge-hover-background | Background on hover of an Outline badge alone, read ahead of --bit-Badge-hover-background so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Badge-outline-active-background` | --bit-Badge-active-background | Background while pressed of an Outline badge alone, read ahead of --bit-Badge-active-background so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Badge-text-color` | --bit-Badge-color | Text and icon color of a Text badge alone, read ahead of --bit-Badge-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Badge-text-background` | --bit-Badge-background | Background of a Text badge alone, read ahead of --bit-Badge-background so a theme can set this variant apart from the other two. The Color parameter leaves it alone. |
| `--bit-Badge-text-border-color` | --bit-Badge-border-color | Border color, in every state, of a Text badge alone, read ahead of --bit-Badge-border-color so a theme can set this variant apart from the other two. The Color parameter leaves it alone. |
| `--bit-Badge-text-hover-background` | --bit-Badge-hover-background | Background on hover of a Text badge alone, read ahead of --bit-Badge-hover-background so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Badge-text-active-background` | --bit-Badge-active-background | Background while pressed of a Text badge alone, read ahead of --bit-Badge-active-background so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Badge-focus-color` | --bit-clr-pri-focus | Keyboard focus ring color of a clickable badge. 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-Badge-border-width` | --bit-shp-brd-width | Border width. |
| `--bit-Badge-radius` | --bit-shp-radius-full | Corner radius. A dot is always a circle. The Shape parameter wins over it. |
| `--bit-Badge-height` | --bit-siz-badge-md | Height, and the smallest width, which keeps a single digit a circle. The Size parameter wins over it. |
| `--bit-Badge-padding` | 0 spacing(0.75) | Padding. The Size parameter wins over it. |
| `--bit-Badge-font-size` | --bit-tpg-fs-sm | Text size. The Size parameter wins over it. |
| `--bit-Badge-font-weight` | --bit-tpg-fw-semibold | Text weight. |
| `--bit-Badge-gap` | spacing(0.5) | Room between the icon and the content. |
| `--bit-Badge-dot-size` | --bit-siz-badge-dot-md | Diameter of a Dot badge. The Size parameter wins over it. |
| `--bit-Badge-inset` | spacing(0.5) | How far an overlaid badge reaches back in over the edge of its child. |
| `--bit-Badge-overlap-inset` | spacing(1.5) | The same inset when Overlap is on. |
| `--bit-Badge-inline-gap` | spacing(0.75) | Room between an Inline badge and its child. |
| `--bit-Badge-z-index` | 1 | Layer an overlaid badge is painted on, one above its child by default. |
| `--bit-Badge-ring-color` | --bit-clr-bg-pri | Color of the Bordered ring; match it to the surface behind the badge. |
| `--bit-Badge-ring-width` | --bit-shp-brd-width-thick | Width of the Bordered ring. |
| `--bit-Badge-pulse-color` | --bit-clr-pri | Color of the Pulse ring. The Color parameter wins over it. |
## Examples
\n**Basic**:
```razor
```
\n**Variant & Shape**:
```razor
```
\n**Content**:
```razor
99%
```
\n**Max, ShowZero & Hidden**:
```razor
Remove one
Add one
Updates
```
\n**Position**:
```razor
Position
> badgePositionList = Enum.GetValues()
.Select(enumValue => new BitDropdownItem
{
Value = enumValue,
Text = enumValue.ToString()
})
.ToList();
```
\n**Overlap & Offset**:
```razor
```
\n**Bordered & Pulse**:
```razor
```
\n**Standalone & Inline**:
```razor
Inbox
Build server
```
\n**OnClick & Href**:
```razor
Receive a message
```
```csharp
private int unread = 3;
```
\n**CSS variables**:
```razor
```
\n**Cascading parameters**:
```razor
```
```csharp
private readonly BitBadgeParams[] badgeParams =
[
new()
{
Max = 99,
Bordered = true,
Shape = BitShape.Rounded,
Variant = BitVariant.Outline,
}
];
```
\n**Color**:
```razor
@foreach (var color in semanticColors)
{
}
```
```csharp
private readonly BitColor[] semanticColors =
[
BitColor.Primary,
BitColor.Secondary,
BitColor.Tertiary,
BitColor.Info,
BitColor.Success,
BitColor.Warning,
BitColor.SevereWarning,
BitColor.Error,
];
```
\n**External Icons**:
```razor
```
\n**Size**:
```razor
```
\n**RTL**:
```razor
Anchor