Badge

The badge overlays whatever it wraps and Content is what it shows. A number is the common case: how much of something is waiting behind the element the badge is attached to. A number is also the only content the badge counts, which is what Max and ShowZero act on. The badge scales itself in as it lands on the page and gives a short bump whenever what it shows changes, so a count ticking over is noticed rather than silently different; both collapse to nothing when the reader asks for reduced motion, which is why this page keeps them off until the animation toggle turns them back on.

The badge offers three variants: Fill (default) paints it in the role color, Outline keeps only the border and the label, and Text drops the border too. A disabled badge keeps its variant and swaps the role color for the disabled one.

Shape is the corner of the badge. Circular (default) rounds it fully, so a single digit is a circle and a longer label a pill; Rounded takes the corner the current theme gives its controls, which is what makes a badge sit next to the rest of a form; and Square drops the radius altogether. A dot is always a circle, whatever the shape says.

Dot shrinks the badge to a plain mark and drops its content and its icon. Use it when the fact that something changed matters more than how much of it there is. The dot scales with the Size of the badge, and since it says nothing on its own, give it a Description so its meaning is not carried by color alone.

Max caps a numeric content: anything above it renders as the max followed by a plus sign, so a counter never grows wider than the room it was given. It reads every numeric type - integral or fractional, not only int - and leaves a string content untouched. A capped badge is the one a reader cannot get the real figure out of, so it carries that figure as its tooltip on its own: hover the second badge below and it reads 100. Title overrides that wherever there is something better to say than the number itself, as the third one does.

A counter that reaches zero has nothing left to report. ShowZero is true by default, so the zero is rendered; set it to false and the badge disappears on its own, which saves keeping a Hidden flag of your own next to the count. An icon or a ContentTemplate is content of its own rather than a number, so it keeps the badge on the page and only the emptied count is taken off it.

Beyond a number, the badge takes a string, an icon (IconName or Icon), both together, or - when text is not enough - a ContentTemplate of your own markup. Reversed flips the order of the icon and the content. Any other value of Content is rendered through its own ToString(). A template is content of its own, so it is what the badge shows and what keeps it on the page: neither Max nor ShowZero reads it. A badge given no content, no icon and no template at all has nothing to report and is not rendered, so a counter bound to nothing leaves no empty mark behind.

String content

Icon

Icon and content, and the same pair reversed

ContentTemplate

Position anchors the badge to one of the fifteen points around its child. The Left and Right ones are physical and stay where they are in right-to-left, while the Start and End ones follow the direction of writing and swap sides with it.

Overlap pulls the badge in towards its child instead of leaving it on the bounding box. Turn it on for a child with a rounded outline - an avatar, a circular button - where a badge sitting on the corner of the box would float away from it.

OffsetX and OffsetY nudge the badge by any CSS length on top of its position, for the cases the fifteen anchors and Overlap do not land exactly on. A positive value moves the badge right and down in both directions of writing, since an offset is a correction for one specific child rather than a part of the layout.

Bordered draws a ring around the badge in the color of the page behind it, so a badge landing on a picture or an avatar keeps an edge of its own instead of dissolving into whatever is underneath it.

Pulse sends a ring expanding out of the badge and fading, for a state that is still going: a sync in flight, a device connecting, a live stream. The ring is decorative - it slows down rather than stops when the reader asks for reduced motion - so pair it with a Description when the state itself matters.

With no child content there is nothing to overlay, so the badge renders standalone: in the normal flow of the page, at its own size, with Position and Overlap no longer applying. That is how a badge is used inside a table cell, a list row or a heading, where it labels the line it is on rather than an element it sits over. To keep the child content and still lay the badge out beside it, use Inline.

Inline keeps the child content and lays the badge out beside it instead of over it, so the badge is given room of its own rather than having to stay small enough not to bury what it sits on. That is the counter at the end of a navigation item, the status next to a heading, the total after a tab label. Overlap stops applying and only the side of Position is read: the Start and Left families put the badge before the child, every other one after it.

Hidden removes the badge from the DOM while its child keeps rendering, for a marker you control yourself. When what you are hiding is an empty counter, ShowZero does it without a flag.

Giving the badge an OnClick handler turns it into a real button: it takes the pointer back from the element underneath it, answers to hover and to the Enter and Space keys, and shows a focus ring. The click stops there rather than carrying on to whatever the badge is sitting on, so a badge over a button is its own target. Without a handler the badge never takes focus and lets every pointer through - it is a label on the element it belongs to, and that element is what a keyboard user reaches. Disabling the badge takes it out of the tab order and stops the handler. For a badge that opens what it counts rather than acting on the page it is already on, give it an Href instead of a handler.

Href turns the badge into a real anchor, for a counter that opens what it counts rather than acting on the page it is already on. It brings everything a click handler cannot: the context menu, the middle click, the address in the status bar and the announcement of a link. Target picks the browsing context it opens in and Rel the relationship to the linked document - a badge opening in a new tab with no Rel of its own is given rel="noopener", which keeps the opened page from reaching back into this one. OnClick can be set alongside it, in which case the handler runs and the navigation still happens. Disabling the badge drops the href and takes the badge out of the tab order, so a disabled link cannot be followed by either the pointer or the keyboard.

A badge says what it says visually, and a number or a colored dot reaches a screen reader as nothing at all. Description is its text alternative: it is rendered into the badge for assistive technologies only, and the visible content is hidden from them so the two are never announced twice. Live adds a polite live region, so a count that changes while the page stays open is announced as it changes - keep it off for a count that only mirrors what is already on the screen. The region is kept on the page whether or not the badge itself is, which is what makes a counter that appears, changes and then disappears announced every time: a live region inserted together with its own text is announced by nothing. What the region reads out is the Description when there is one and the counter itself otherwise; a ContentTemplate is markup neither of them can be read out of, so a badge showing one keeps its own voice and needs a Description before Live has anything to announce. AriaLabel is the other half: where a Description says what the badge shows, the label names the badge as a control. A badge that is a button or a link is what a screen reader lands on, so the label moves onto that control itself - which is what an icon-only or dotted one, carrying no text to be named by, needs before it becomes either. A Description already names the control, so the two are not set together.

Color picks the role the badge is painted in. The eight semantic roles carry a meaning - Error for something that needs attention, Success for something that went through - while the background, foreground and border roles are the neutral surfaces of the theme, for a badge that should not shout. Every role works with all three variants.

Primary

Secondary

Tertiary

Info

Success

Warning

SevereWarning

Error

Backgrounds, foregrounds & borders:

PrimaryBackground, SecondaryBackground, TertiaryBackground

PrimaryForeground, SecondaryForeground, TertiaryForeground

PrimaryBorder, SecondaryBorder, TertiaryBorder

Disabled:

Primary

Secondary

Tertiary

Info

Success

Warning

SevereWarning

Error

Use icons from external libraries like FontAwesome and Bootstrap Icons with the Icon parameter.

See the BitIconInfo section in the parameters table for usage.

Size sets the height, the type size and the inset of the badge, and the diameter of a dot along with them. A counter is never narrower than it is tall, so a single digit stays a circle at every size.

Small

Medium

Large

Style and Class land on the root of the component - the box that wraps the child content - while Styles and Classes reach every part of it on its own: the root, the wrapper the badge is positioned inside of, the badge itself, its icon, its content, its visually hidden description and its live region. The badge also reads a handful of CSS variables off its root, for what no parameter covers: --bit-bdg-clr and --bit-bdg-clr-txt for a color outside the theme roles, --bit-bdg-clr-ring for the color a Bordered ring is drawn in, --bit-bdg-gap for the room between an inline badge and its child, and --bit-bdg-zin for the layer an overlaid badge is painted on, which it sits one above its child on by default so nothing the child raises can cover it.

Component's Style & Class:

CSS variables:

Styles & Classes:

Use BitBadge in right-to-left (RTL). The Start and End positions follow the direction of writing and move to the other side of the child with it, while the Left and Right ones stay where they are. An icon and its content swap sides along with the layout.

جدید


پیش‌نویس