Skip to content
BlazorUI

Notifications

Tag

Bit.BlazorUIChip

Tag is the compact chip for an attribute, a person or an asset. It takes a label and a second line, glyphs or a picture at either end, and three variants, sizes and shapes across the color palette. A dismiss handler grows a close button that also answers Delete and Backspace; a click handler or a URL makes it a real button or anchor; a bound Selected makes it a filter chip that reports aria-pressed.

Usage

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

Basic

Text is what the tag says. On its own a tag is an inline label, not a control: it takes no focus and reacts to nothing.

Basic tag Design Archived

Variant & Shape

Variant: Fill (default), Outline and Text. Shape: Rounded (default) follows the chip corner of the theme, Circular is always a pill and Square has no radius. A disabled tag keeps both.

Fill Outline Text

Rounded Circular Square

Fill Outline Text

Icon

IconName leads the tag, SecondaryIconName closes it (a chevron, an arrow). Both are decorative - hidden from screen readers - and sized to the text. Reversed mirrors the whole row.

Calendar Status Both ends Reversed

Image & Secondary text

IconUrl puts a picture where the icon goes, cropped to a circle - an avatar, a flag, a logo. It renders with an empty alt unless IconAlt says what the label does not. SecondaryText adds a smaller second line under the label.

Annie Lindqvist Annie LindqvistSoftware engineer Assigned to Annie LindqvistAwaiting review Storage12.4 GB used

Dismiss

OnDismiss adds a close button, also triggered by Delete or Backspace. It is named after the tag ("Remove Design"); DismissLabelFormat rewords or translates that for every tag, DismissLabel replaces it for one, and DismissIconName / DismissIcon change the glyph.

The tag never removes itself. After removing one, call FocusAsync on its neighbor so the keyboard keeps its place in the list - try it with Tab and Delete below.

DesignResearchDocs

Custom glyph Formatted label Disabled

Click

OnClick makes the tag a real button: focusable, activated by Enter and Space, with hover, press and focus states. A click on its dismiss button never reaches it. StopPropagation keeps its click from reaching a clickable parent.


A clickable card:


Tag clicks: 0, dismissals: 0, card clicks: 0

Selection

Binding Selected (or setting OnChange) makes a filter chip: a toggle button reporting aria-pressed, with a checkmark so the state is not carried by color alone. SelectedIconName changes the checkmark, HideSelectedIcon removes it.


Selected: In progress



DefaultSelected gives a tag its own state, with no field behind it. OnChanging runs before each change and can cancel it. A Selected set without a callback is a static state the tag cannot change.


Static selection

Link

Href makes the tag a real anchor, with Target, Rel and Download. A new-tab link gets rel="noopener" unless Rel says otherwise, and is announced "(opens in a new tab)" - NewTabHint rewords it, an empty one removes it. A disabled link drops its href and leaves the tab order. A Selected link reports aria-current, whose value AriaCurrent sets (Page for the page you are on); a click navigates rather than toggling it.

Iconography Docs(opens in a new tab) Source(opens GitHub in a new tab) Logo Disabled This page

Templates

ChildContent replaces the text only - icons, the picture and the checkmark still render around it. PrefixTemplate and SuffixTemplate add markup at either end instead: initials, a dot, a count. They are part of the tag's one target, so keep controls out of them and the name in the label.

Alex (owner)

APAlex ParkerProduct designer Open issues24

NoWrap & FullWidth

A tag wraps by default. NoWrap keeps it on one line with an ellipsis - pair it with a Title so the cut-off text stays reachable. FullWidth stretches the tag to its container and pushes trailing glyphs and the dismiss button to the end.

A tag with a label long enough to wrap onto a second line A tag with a label long enough to wrap onto a second line Full width and dismissible

Accessibility

A tag with no words needs an AriaLabel. It names the button or link the tag becomes; on a static tag it is read in place of the content ("3" becomes "3 unread messages"). AriaDescription is read after the name - on a static dismissible tag, by its dismiss button too.

Pinned to the top 3 unread messages Shows only the items you own OfflineDismissing hides the notice, not the problem


A plain tag takes no focus. TabIndex puts it in the tab order, and FocusAsync focuses it - or, on any other tag, the button, link or dismiss button it renders. AllowDisabledFocus keeps a disabled control in the tab order as aria-disabled, so its description still says why it is unavailable.

A plain tag with a TabIndex Unavailable while offline

Cascading parameters

BitParams hands a BitTagParams to every tag under it, so a filter bar sets its look once. The values are defaults, not overrides: a tag keeps whatever it sets itself.

Design Research Urgent

Outside the cascade

Color

Color picks the role from the theme; every role pairs with all three variants, and a disabled tag takes that role's disabled colors.

Primary  Primary  Primary

Secondary  Secondary  Secondary

Tertiary  Tertiary  Tertiary

Info  Info  Info

Success  Success  Success

Warning  Warning  Warning

SevereWarning  SevereWarning  SevereWarning

Error  Error  Error

PrimaryBackground  PrimaryBackground  PrimaryBackground

SecondaryBackground  SecondaryBackground  SecondaryBackground

TertiaryBackground  TertiaryBackground  TertiaryBackground


PrimaryForeground  PrimaryForeground  PrimaryForeground

SecondaryForeground  SecondaryForeground  SecondaryForeground

TertiaryForeground  TertiaryForeground  TertiaryForeground


PrimaryBorder  PrimaryBorder  PrimaryBorder

SecondaryBorder  SecondaryBorder  SecondaryBorder

TertiaryBorder  TertiaryBorder  TertiaryBorder


Disabled:

Primary  Secondary  Tertiary  Info  Success  Warning  SevereWarning  Error

PrimaryBackground  SecondaryBackground  TertiaryBackground

PrimaryForeground  SecondaryForeground  TertiaryForeground

PrimaryBorder  SecondaryBorder  TertiaryBorder

External Icons

Icon, SecondaryIcon, DismissIcon and SelectedIcon take a BitIconInfo from any icon library (FontAwesome, Bootstrap Icons, ...); the glyph is sized to the text whatever scale the library brings.

FontAwesome:

House Heart GitHub Dismiss Selected Trailing


Bootstrap:

House Heart GitHub Dismiss Selected Trailing

Size

Small, Medium (default) and Large set the type, the inset and the height - the theme's --bit-siz-chip-* tokens, so a preset such as Material resizes every tag. From Medium up the dismiss button meets the 24px minimum target size of WCAG 2.2.

Small Small

Medium Medium

Large Large

Style & Class

Style and Class land on the root; Styles and Classes reach each part through BitTagClassStyles, including the selected state.

Styled Tag Classed Tag

Styleswith a second line Classes


CSS variables re-skin what no parameter covers. They inherit, so one set on an ancestor restyles every tag inside it, and one set in Style restyles that tag alone.

Bold pill Elevated

A long label cut by the max width

RTL

In right-to-left the icon, the label, the dismiss button and their insets all swap sides; Reversed still mirrors whatever that order is.

برچسب طراحی پژوهش معکوس

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.

BitTag CSS variables

Name Default value Description
--bit-Tag-color Per Variant, from the Color role Text and glyphs at rest.
--bit-Tag-background Per Variant, from the Color role Background at rest.
--bit-Tag-border-color Per Variant, from the Color role Rule at rest.
--bit-Tag-icon-color The text color Leading, trailing and checkmark glyphs (not the dismiss glyph). Disabled tags ignore it.
--bit-Tag-hover-background Per Variant, a step deeper while selected Background of a hovered clickable content or dismiss button.
--bit-Tag-active-background Per Variant, a step deeper while selected Background of a pressed clickable content or dismiss button.
--bit-Tag-selected-color --bit-Tag-color Text and glyphs of a selected tag.
--bit-Tag-selected-background Per Variant, from the Color role Background of a selected tag.
--bit-Tag-selected-border-color Per Variant, from the Color role Rule of a selected tag.
--bit-Tag-disabled-color The Color role's disabled text color Text and glyphs of a disabled tag.
--bit-Tag-disabled-background Per Variant, from the Color role Background of a disabled tag.
--bit-Tag-disabled-border-color Per Variant, from the Color role Rule of a disabled tag.
--bit-Tag-focus-color The text color Color of the inset focus outline.
--bit-Tag-radius --bit-shp-radius-chip Corner of a Rounded (default Shape) tag; Circular and Square keep their own.
--bit-Tag-border-width --bit-shp-brd-width Width of the rule.
--bit-Tag-shadow none Elevation of the tag, e.g. var(--bit-shd-card) for an elevated chip.
--bit-Tag-min-height --bit-siz-chip-{sm,md,lg} Smallest height inside the rule; the tag still grows with wrapped text.
--bit-Tag-max-width 100% Widest the tag gets before it wraps or, with NoWrap, ellipsizes.
--bit-Tag-padding-x Per Size (half of --bit-siz-ctrl-pad-x-*) Inline inset of the content and the outer inset of the dismiss button.
--bit-Tag-padding-y Per Size Block inset of the content.
--bit-Tag-gap Per Size Room between the icon, the label and the other parts of the content.
--bit-Tag-font-size Per Size, from the type ramp Text size.
--bit-Tag-font-weight --bit-tpg-font-weight Text weight (a Text with a SecondaryText under it is semibold).
--bit-Tag-secondary-font-size Per Size, one step under the text Size of the SecondaryText line.
--bit-Tag-icon-size 1em Size of every glyph, the dismiss glyph included.
--bit-Tag-image-size Per Size Size of the IconUrl picture.

API

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

BitTag parameters

Name Type Default value Description
AllowDisabledFocus bool false Keeps a disabled button, link or dismiss button in the tab order, reporting aria-disabled instead of disabled.
AriaCurrent BitNavAriaCurrent BitNavAriaCurrent.True The aria-current value a selected link tag reports. A toggle tag reports aria-pressed instead.
AriaDescription string? null A description screen readers read after the name, through a visually hidden element referenced by aria-describedby.
ChildContent RenderFragment? null Custom content in place of Text and SecondaryText; the icons, the image and the checkmark still render around it.
Classes BitTagClassStyles? null Custom CSS classes for different parts of the tag.
Color BitColor? null The general color of the tag.
DefaultSelected bool? null The initial selection of a tag that keeps its own state (an uncontrolled toggle).
DismissIcon BitIconInfo? null The dismiss glyph from an external icon library. Takes precedence over DismissIconName.
DismissIconName string? null The dismiss glyph from the built-in icons. Defaults to Cancel.
DismissLabel string? null The accessible name and tooltip of the dismiss button. Defaults to DismissLabelFormat applied to Text (or AriaLabel), else "Dismiss".
DismissLabelFormat string? null The format of the dismiss button name, where {0} is the Text. Defaults to "Remove {0}"; use it to reword or translate.
Download string? null Downloads the Href instead of navigating to it, suggesting this file name (empty keeps the server's).
FullWidth bool false Stretches the tag to the width of its container.
HideSelectedIcon bool false Hides the checkmark of a selected tag.
Href string? null Makes the tag a link to this URL. A disabled link drops the href and leaves the tab order.
Icon BitIconInfo? null The leading glyph from an external icon library. Takes precedence over IconName.
IconAlt string? null The alt text of the IconUrl picture, which is decorative (empty alt) by default.
IconName string? null The leading glyph from the built-in icons.
IconUrl string? null A picture shown in place of the icon, cropped to a circle. Ignored while Icon or IconName is set.
NewTabHint string? null The announcement of a Target="_blank" link, "(opens in a new tab)" by default; an empty value removes it.
NoWrap bool false Keeps the text on one line, ending it with an ellipsis where it does not fit.
OnChange EventCallback<bool> Called after Selected changes. Setting it makes the tag a toggle (except a link, whose click navigates).
OnChanging EventCallback<BitTagChangeArgs> Called (and awaited) before Selected changes; set Cancel on the args to keep the current state.
OnClick EventCallback<MouseEventArgs> Called on click; setting it makes the tag a button.
OnDismiss EventCallback<MouseEventArgs> Called on dismiss; setting it shows the dismiss button. Delete and Backspace trigger it too.
PrefixTemplate RenderFragment? null Custom markup added at the start of the tag, before the icon.
Rel BitLinkRels? null The rel of the link. A _blank link without one gets rel="noopener".
Reversed bool false Mirrors the order of the whole row, dismiss button included.
SecondaryIcon BitIconInfo? null The trailing glyph from an external icon library. Takes precedence over SecondaryIconName.
SecondaryIconName string? null The trailing glyph from the built-in icons, after the label and before the dismiss button.
SecondaryText string? null A smaller second line under the Text.
Selected bool false The selected state: selected colors and a checkmark. Binding it makes the tag a toggle reporting aria-pressed (aria-current on a link).
SelectedChanged EventCallback<bool> Called when Selected changes; what @bind-Selected uses.
SelectedIcon BitIconInfo? null The checkmark glyph from an external icon library. Takes precedence over SelectedIconName.
SelectedIconName string? null The checkmark glyph from the built-in icons. Defaults to Accept.
Shape BitShape? null The corner shape of the tag. A tag takes its box from its own content, so Circle has no proportions to impose and rounds the ends fully, the same as Pill.
Size BitSize? null The size of the tag.
StopPropagation bool false Stops the click from reaching the parent elements.
Styles BitTagClassStyles? null Custom CSS styles for different parts of the tag.
SuffixTemplate RenderFragment? null Custom markup added at the end of the tag, before the dismiss button.
Target string? null Where the link opens, e.g. _blank.
Text string? null The text of the tag.
Title string? null The native tooltip of the tag, e.g. the full text behind a NoWrap ellipsis.
Variant BitVariant? null The visual variant of the tag.

BitTag public members

Name Type Default value Description
FocusAsync ValueTask Focuses the tag's button or link, else its dismiss button, else the tag itself (which needs a TabIndex).

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.

BitTagClassStyles properties

Name Type Default value Description
Root string? null Custom CSS classes/styles for the root element of the BitTag.
Content string? null Custom CSS classes/styles for the content element of the BitTag: the anchor or button of a link or clickable tag, a span otherwise.
Label string? null Custom CSS classes/styles for the label of the BitTag, which is the element holding its text and secondary text.
Text string? null Custom CSS classes/styles for the text of the BitTag.
SecondaryText string? null Custom CSS classes/styles for the secondary text of the BitTag.
Icon string? null Custom CSS classes/styles for the icon of the BitTag.
Image string? null Custom CSS classes/styles for the image of the BitTag.
SecondaryIcon string? null Custom CSS classes/styles for the trailing icon of the BitTag, which is rendered after the label.
Selected string? null Custom CSS classes/styles for the root element of the BitTag while it is selected.
SelectedIcon string? null Custom CSS classes/styles for the checkmark icon a selected BitTag shows.
DismissButton string? null Custom CSS classes/styles for the dismiss button of the BitTag.
DismissIcon string? null Custom CSS classes/styles for the dismiss icon of the BitTag.

BitTagChangeArgs properties

The arguments of the OnChanging callback of the BitTag.

Name Type Default value Description
Value bool The selection state the tag is about to move to.
Cancel bool false Set to true to cancel the change and keep the current selection state.

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.

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.

BitSize enum

Name Value Description
Small 0 The small size.
Medium 1 The medium size.
Large 2 The large size.

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.