Skip to content
BlazorUI

Notifications

Badge

Bit.BlazorUI

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.

Usage

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

Basic

The badge overlays whatever it wraps and shows its Content. It scales in as it lands and bumps whenever what it shows changes; both collapse under reduced motion, which this page keeps on until the animation toggle turns motion back on.


63

Variant & Shape

Variant: Fill (default), Outline or Text. Shape: Circular (default), Rounded (the theme's control corner) or Square. A disabled badge keeps its variant and takes the disabled colors.


84 84 84


84 84 84


New New New

Content

Beyond a number, Content takes a string or any value (rendered through ToString()). IconName / Icon add a glyph, Reversed puts it after the content, and ContentTemplate replaces both with your own markup. A badge given nothing to show is not rendered.


Text Sent Sent 99%

Max, ShowZero & Hidden

Max caps a number of any numeric type (99+). ShowZero=false takes an emptied counter off the page, and Hidden removes the badge while its child keeps rendering.


60 63+ 99+


3 3 3


Dot

Dot drops the content and shrinks the badge to a mark scaled by Size. A dot says nothing on its own, so give it a Description: the text screen readers read in its place (see Accessibility).


New mail New alerts Updates available

Position

Position anchors the badge to one of fifteen points around its child. Left/Right are physical; Start/End follow the direction of writing.

63

Overlap & Offset

Overlap pulls the badge in over a rounded child such as an avatar. OffsetX / OffsetY nudge it by any CSS length; positive values move it right and down in both directions of writing.


Avatar
8
Avatar
8
Avatar
8

Bordered & Pulse

Bordered rings the badge in the page color so it keeps an edge over a busy child. Pulse sends a fading ring out of it for a state still in progress; under reduced motion it stops and stays as a still halo.


Avatar
Online
Avatar
Online Syncing 3

Standalone & Inline

Without child content the badge stands alone in the flow - a status in a table cell or a heading. It takes the pointer there (an overlaid one leaves it to its child), so a capped count shows its real figure on hover, which Title replaces. Inline keeps the child and lays the badge beside it; only the side of Position is read (Start/Left before the child, the rest after).


Draft Beta Degraded 999+ 999+


Inbox

24

Build server

Operational

OnClick & Href

OnClick makes the badge a real button and Href a real link: focusable, keyboard-operable, with a focus ring and a 24px hit area. The click stops at the badge. Target and Rel work as on any link (_blank adds noopener). Disabled, it leaves the tab order and drops the href. Without either, the badge never takes focus.


Docs Source

Accessibility

Description is the badge's text alternative: read by screen readers in place of the visible number, glyph or dot. Live announces changes politely, even as the badge appears and disappears; keep it off for counts that only mirror the screen. AriaLabel names a button or link badge (a Description then describes it); on a plain dot or icon-only badge it serves as the text alternative, while one showing a count keeps saying the count. Over a focusable child, fold the count into the child's name and mark the badge Decorative so it is not read twice.


3 unread messages Online 3 unread


CSS variables

The public --bit-Badge-* variables (see the CSS variables table) restyle what no parameter covers. They inherit, so set them on :root or on any ancestor - a plain element around the badges, as here - or on one badge's Style (see Style & Class). A disabled badge keeps the theme's disabled colors.


Subtle Custom Tall Recording


4 12 9+

Cascading parameters

BitParams carries a BitBadgeParams to every badge under it, so a toolbar sets the shared look once. It is a default, not an override: a badge keeps whatever it sets itself (the last one keeps its own Variant).


4 99+ 7

Color

Color picks the theme role the badge is painted in, with every variant. The semantic roles carry a meaning; the background, foreground and border roles are the theme's neutral surfaces, for a badge that should not shout.


Primary

84 84 84


Secondary

84 84 84


Tertiary

84 84 84


Info

84 84 84


Success

84 84 84


Warning

84 84 84


SevereWarning

84 84 84


Error

84 84 84


PrimaryBackground, SecondaryBackground, TertiaryBackground

84 84 84


PrimaryForeground, SecondaryForeground, TertiaryForeground

84 84 84


PrimaryBorder, SecondaryBorder, TertiaryBorder

84 84 84

External Icons

Use icons from external libraries like FontAwesome and Bootstrap Icons with the Icon parameter.
See the BitIconInfo section in the parameters table for usage.


4 63


3

Size

Size sets the height, type size and padding, and the diameter of a dot. A single digit stays a circle at every size. The heights and dots are theme tokens (--bit-siz-badge-*), so each design-system preset sizes badges its own way.


New mail New mail New mail


84 84 84


Small Medium Large

Style & Class

Style and Class land on the root, which wraps the child. Styles and Classes reach every part: the root, the wrapper the badge is positioned in, the badge, its icon, its content, its hidden description and its live region.


Component's Style & Class:

84
Anchor
84



Styles & Classes:

84 84

RTL

Use BitBadge in right-to-left (RTL). Start/End positions and the icon order follow the direction; Left/Right stay put.


63 63 جدید پیش‌نویس

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 that one alone. Leave a variable unset and the component falls back to the theme token beside it.

BitBadge CSS variables

Name Default value Description
--bit-Badge-color Per variant, from the Color role Text and icon color. In the Outline variant it is also the border color.
--bit-Badge-background Per variant, from the Color role Background. In the Fill variant it is also the border color.
--bit-Badge-border-color The background (Fill), the text color (Outline), transparent (Text) Border color, in every state.
--bit-Badge-hover-background Per variant, from the Color role Background of a clickable (OnClick or Href) badge on hover. Set it together with --bit-Badge-background.
--bit-Badge-active-background Per variant, from the Color role Background of a clickable badge while pressed.
--bit-Badge-focus-color The Color role's focus color Keyboard focus ring color of a clickable badge.
--bit-Badge-border-width --bit-shp-brd-width Border width.
--bit-Badge-radius Per Shape Corner radius. A dot is always a circle.
--bit-Badge-height --bit-siz-badge-{sm,md,lg}, per Size Height, and the smallest width, which keeps a single digit a circle.
--bit-Badge-padding Per Size Padding.
--bit-Badge-font-size Per Size, from the type ramp Text size.
--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-{sm,md,lg}, per Size Diameter of a Dot badge.
--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 The Color role's main color Color of the Pulse ring.

API

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

BitBadge 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.
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. With no value of its own, a badge opening in a new browsing context gets rel="noopener" automatically.
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.
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.
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.

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.
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.

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.

BitColor enum

Name Value Description
Primary 0 Info 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 badge.
Medium 1 The medium size badge.
Large 2 The large size badge.

BitShape enum

Name Value Description
Rounded 0 The corner radius the current theme gives to this kind of surface.
Square 1 Sharp corners with no radius at all.
Pill 2 Fully rounded ends: 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.

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.

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.