Tag

Text is what the tag says. On its own the tag is a label rather than a control: it takes no focus, it reacts to nothing, and it is a plain inline element that sits inside a sentence without breaking the line it is on. Everything else on this page is something added on top of that - a glyph, a dismiss button, a click handler, a URL, a selection.

The tag offers three variants: Fill (default) paints the whole chip in the role color, Outline keeps only the rule and the label, and Text drops the rule too and leaves the label alone. A disabled tag keeps its variant and swaps the role color for the disabled one.

Shape is the corner of the tag. Rounded (default) takes the chip corner of the current theme, which is what keeps a tag in the same visual language as the chips a TagsInput or a multi-select Dropdown draws in its field; Circular pins it to a pill and Square drops the radius altogether, whatever the theme says.

IconName puts a glyph at the head of the tag, which is what lets a row of tags be told apart at a glance rather than read one by one. SecondaryIconName puts one at the other end, after the label and before the dismiss button, for the glyph that closes the tag rather than opening it - the chevron of a chip that drops a menu, the arrow of one that leads somewhere. It sits inside whatever the tag became, so it is part of the same target the pointer and the keyboard activate rather than a control of its own. Both glyphs are decorative - they are hidden from assistive technologies, since the label between them already says what the tag is - and both are normalized to the size of that label, so an icon from any library sits on the same line as the words. Reversed mirrors the order of the whole tag, which swaps the two ends over.

IconUrl puts a picture where the glyph would go - the avatar of the person the tag stands for, a flag, a logo. It is cropped to a circle the height of the label, so a portrait of any aspect ratio reads as an avatar, and it is only rendered while no Icon or IconName is set, since the two occupy the same place. The picture is decorative next to the name beside it, so it carries an empty alt unless IconAlt says otherwise - as on the third tag below, where the label says what the state is and only the picture says whose it is.

SecondaryText adds a second line under the label, for what qualifies the tag rather than what names it - the role under a person, the count under a category, the unit under a value. It is set one step smaller and at the regular weight, and the line above it is lifted to semibold to answer it; neither is dimmed, since an opacity over a painted chip takes the contrast with it. Keep it short: a tag is a label, not a card.

Setting OnDismiss grows a close button at the end of the tag. It is a real button standing next to the content rather than inside it, so it takes focus of its own, it is activated with Enter and Space, and a click on it never reaches the tag's own OnClick. It can also be triggered with the Delete or the Backspace key from anywhere inside the tag, which is what a keyboard user reaches for once the pointer has shown them the button. DismissIconName and DismissIcon change the glyph, and DismissLabel its accessible name and tooltip. With no label of its own the button is named after the tag it takes away - "Remove Design" - rather than being one of a row of buttons all called "Dismiss", which names none of them. DismissLabelFormat is what changes that wording for a whole list at once and what translates it, since the default is English; DismissLabel replaces the name of a single tag outright. The tag never removes itself: what the handler does with the dismissal is up to the app, and FocusAsync is what puts the keyboard back on the list afterwards.

Setting OnClick turns the tag into a real button: it enters the tab order, it is activated with Enter and Space, it answers hover and press with a shade of its own color, and it wears a focus ring - none of which a click handler on a plain element reproduces. Disabling the tag disables that button, so it can be reached by neither the pointer nor the keyboard. A control needs a name, so a tag that carries no words of its own needs an AriaLabel as soon as it becomes one. StopPropagation keeps the click inside the tag, for a tag that sits in something else that reacts to one - a row, a card, a list item - where activating the tag should not also activate what holds it.

Clicked 0 times, dismissed 0 times, card clicked 0 times.

Href turns the tag into a real anchor, for a tag that opens what it stands for 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 tag 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. Download turns the tag into one that saves what it points at instead of navigating to it, taking its value as the suggested file name. Disabling the tag drops the href and takes it out of the tab order. A Selected link reports itself through aria-current, and AriaCurrent is what that says: leave it at True for the picked one of a set of filters, and set it to Page for a tag standing for the page the reader is already on.

Binding Selected - or setting OnChange - turns the tag into a filter chip: a toggle button that flips its own state on every activation and reports it to assistive technologies through aria-pressed, so a screen reader announces it as pressed or not pressed rather than leaving the state to color alone. A selected tag deepens its paint and shows a checkmark in front of its content; SelectedIconName changes that glyph and HideSelectedIcon removes it. Set Selected without either callback and it is a static "this one is picked" state the app drives on its own, and one the tag is not allowed to change; DefaultSelected is the other half of that - a tag that keeps its own selection, with no field in the app behind it. OnChanging runs before every change and can call it off, which is what a filter that has to be confirmed - or saved - before it applies needs. A selected tag that is a link reports itself as aria-current instead, since aria-pressed belongs to a button and would say nothing on an anchor.

Selected: In progress

ChildContent replaces the label of the tag with markup of your own. It replaces the text only: an icon, a picture, the checkmark of a selected tag and a trailing SecondaryIcon all keep rendering around it, so a template does not have to reproduce them.

PrefixTemplate and SuffixTemplate are the other half of that: markup added beside the label rather than in place of it, at the very head and the very end of the tag. They are what the leading and trailing slots need when a glyph is not enough - an avatar with initials, a colored dot, a count - and they leave the two lines of the label to Text and SecondaryText. All three live inside whatever the tag became, so they are part of the same target the pointer and the keyboard activate; that is also why a control of your own does not belong in them - a control inside a button is one no assistive technology can reach - and why nothing in them names the tag, which is still the job of the label or the AriaLabel.

A tag wraps onto as many lines as its content needs by default, which is what keeps a long label readable. NoWrap keeps it on a single line and ends it with an ellipsis wherever it does not fit, for a layout that has a width of its own to protect - a row of filters, a cell of a grid. Pair it with a Title so the part that was cut off is still reachable: a truncated label a reader cannot recover is a label that says nothing.

FullWidth stretches the tag to the width of whatever holds it instead of letting it shrink to its content. Use it for a tag standing on a line of its own - in a narrow side panel, or as a row of a stacked list - where a chip hugging its label leaves the line looking unfinished. The dismiss button stays at the end of the tag as it grows, and so does a trailing SecondaryIcon: the room a stretched tag gains belongs to the label, which is what pushes a trailing glyph to the far end rather than leaving it stranded against the words.

Full width
Full width and dismissible
Full width with a trailing glyph

FocusAsync gives the keyboard focus to whatever the tag offers it: the anchor or the button it becomes while it is a control, and the dismiss button of a tag that has only that. A list of dismissible tags is what needs it - the focus left on a tag that has just been removed falls back to the top of the document, and the keyboard user loses their place in the list. Removing a tag below moves the focus onto the tag that took its place, or onto the last one when the end of the list goes. A tag that is neither a control nor dismissible has nothing inside it to focus, so a TabIndex given to that one lands on the tag itself - which is what puts a plain tag in the tab sequence and what FocusAsync then focuses. Without one a plain tag stays what it is: a label, which takes no focus at all.

A plain tag is a label, so it takes no focus and needs no name of its own - the words in it are the name. Everything that makes it a control changes that: an OnClick, an Href or a selection turns it into a real button or anchor, and a control needs a name, so AriaLabel moves onto that control and is what an icon-only tag has to be given before it becomes one. On a tag that is not a control and has no words in it either, the same label is carried as text no one can see, since an aria-label on an element with no role of its own is not something every screen reader reads. AriaDescription adds what is said after that name - why a filter is unavailable, what dismissing will do - and lands on whichever element carries the name. The dismiss button is a control of its own, already named after the tag it removes; DismissLabelFormat translates that name and DismissLabel replaces it where it needs to say something else. Icons and pictures inside the tag are hidden from assistive technologies, since the label beside them already says what the tag is, and a selected tag reports its state through aria-pressed - or, when it is a link, through the aria-current that AriaCurrent spells out - rather than through color alone. A tag that is neither a control nor dismissible has nothing inside it to focus, so the TabIndex of that one lands on the tag itself and is what puts a plain tag in the tab sequence. The tag also keeps its rule, its selection and its disabled state in a forced-colors mode, where every color it paints is discarded.

Offering a range of specialized color variants, providing visual cues for specific actions or states within your application. Every role pairs with all three variants, and the disabled state of each is the disabled slot of the same role rather than a flat grey.

PrimaryBackground  PrimaryBackground  PrimaryBackground

SecondaryBackground  SecondaryBackground  SecondaryBackground

TertiaryBackground  TertiaryBackground  TertiaryBackground

Disabled:

PrimaryBackground  SecondaryBackground  TertiaryBackground

Use icons from external libraries like FontAwesome and Bootstrap Icons with the Icon parameter and BitIconInfo. A glyph from any of them is normalized back to the size of the label beside it, so it sits on the same line as the words whatever type scale the library it came from brings. SecondaryIcon, DismissIcon and SelectedIcon take the same values, so the trailing glyph, the close button and the checkmark of a selected tag can all come from the same set as the one in front of the label.

FontAwesome:

Bootstrap:

Three sizes set the type, the height and the inset of the tag together, so a tag stays a chip at every one of them. The inline inset is taken from the control padding of the current theme rather than from a fixed number, which is what keeps a tag in proportion under a theme whose corner is rounder or whose density is tighter.

Empower customization by overriding default styles and classes, allowing tailored design modifications to suit specific UI requirements. Style and Class land on the root of the tag, while Styles and Classes reach every part of it separately - the content box the tag becomes when it is a control, the label, the text, the secondary text, the icon, the image, the selected state and the dismiss button with its glyph.

Component's Style & Class:

Styles & Classes:

Use BitTag in right-to-left (RTL). The icon, the label and the dismiss button all follow the direction of writing and swap sides with it, and so do the insets that keep them off the rule. Reversed stays a mirror of whatever that order is rather than a second way of saying right-to-left, so the two can be combined.