# Tag
**Also known as:** Chip
## Description
Tag is the compact chip that stands for an attribute, a person or an asset. It takes a label, a second line under it, an icon or a picture at its head and a second glyph at its end, and comes in three variants, three sizes and three corner shapes across the whole color palette. Give it a dismiss handler and it grows a close button that answers the pointer, the keyboard and the Delete key, and that names the tag it removes; give it a click handler or a URL and it becomes a real button or a real anchor rather than an element that merely reacts to a click; bind its Selected value and it becomes a filter chip that reports its own state to assistive technologies. It wraps onto as many lines as its content needs, truncates to a single one or stretches to the width of whatever holds it, and it can be focused from code - which is what a list of dismissible tags needs once one of them is gone.
## Parameters
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| AriaCurrent | `BitNavAriaCurrent` | BitNavAriaCurrent.True | What a selected tag that is a link reports itself as through aria-current. It only ever reaches the anchor the tag becomes while Href is set - a tag that is a button reports its selection through aria-pressed instead. |
| AriaDescription | `string?` | null | The detailed description of the tag for the benefit of screen readers, rendered into a visually hidden element the tag points at with aria-describedby. |
| ChildContent | `RenderFragment?` | null | Child content of component, the content that the tag will apply to. It replaces the Text and the SecondaryText only; an icon, an image, the checkmark of a selected tag and a trailing SecondaryIcon all keep rendering around it. Use the PrefixTemplate and the SuffixTemplate for markup that belongs beside the label rather than in place of 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 value of Selected for a tag that keeps its own selection: setting it is the whole of what an uncontrolled filter chip needs. A Selected that is set one way, without binding, is one the tag itself is not allowed to change. |
| DismissIcon | `BitIconInfo?` | null | Gets or sets the icon to use for the dismiss button using custom CSS classes for external icon libraries. Takes precedence over DismissIconName when both are set. Defaults to the built-in Cancel icon when neither is set. |
| DismissIconName | `string?` | null | Gets or sets the name of the icon to use for the dismiss button from the built-in Fluent UI icons. Defaults to Cancel when not set. For external icon libraries, use DismissIcon instead. |
| DismissLabel | `string?` | null | The accessible name and the tooltip of the dismiss button. With no value it is named after the Text of the tag through the DismissLabelFormat, and falls back to "Dismiss" on a tag that carries no text of its own. |
| DismissLabelFormat | `string?` | null | The format the dismiss button is named by while it has no DismissLabel of its own, where {0} is the Text of the tag. Defaults to "Remove {0}", which is also what translating that name goes through. |
| Download | `string?` | null | Prompts the browser to download the Href of the tag rather than to navigate to it, using the value as the suggested file name. An empty string keeps the name the server suggests. |
| FullWidth | `bool` | false | Stretches the tag to fill the width of whatever holds it, instead of shrinking to its content. |
| HideSelectedIcon | `bool` | false | Hides the checkmark a selected tag shows in front of its content. |
| Href | `string?` | null | The URL the tag navigates to, which also turns the tag into a link. A disabled tag drops the href and 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. |
| IconAlt | `string?` | null | The text alternative of the IconUrl picture, which is decorative and renders with an empty alt by default. |
| IconName | `string?` | null | Gets or sets the name of the icon to display from the built-in Fluent UI icons. For external icon libraries, use Icon instead. |
| IconUrl | `string?` | null | The URL of a picture to show in place of the icon, cropped to a circle the height of the label. It is only rendered while neither Icon nor IconName is set. |
| NoWrap | `bool` | false | Keeps the content of the tag on a single line and ends it with an ellipsis where it does not fit. |
| OnChange | `EventCallback<bool>` | | Callback for when the Selected value of the tag has changed. Setting it - or binding Selected - is what turns the tag into a toggle. |
| OnChanging | `EventCallback<BitTagChangeArgs>` | | Callback invoked before the Selected value changes, letting the change be cancelled by setting Cancel on the args. Since it is awaited, it can also run asynchronous work first. |
| OnClick | `EventCallback<MouseEventArgs>` | | Click event handler of the tag, which also turns the tag into a real button: focusable, activated with Enter and Space, and disabled along with the tag. |
| OnDismiss | `EventCallback<MouseEventArgs>` | | Dismiss button click event, if set the dismiss icon will show up. It can also be triggered with the Delete and the Backspace keys from any control the tag renders, and with no DismissLabel of its own the button takes the Text of the tag for its name. |
| PrefixTemplate | `RenderFragment?` | null | Custom markup rendered at the head of the tag, ahead of the icon or the picture. It is added rather than substituted, so an icon, an image and the checkmark of a selected tag all keep rendering alongside it. |
| Rel | `BitLinkRels?` | null | The relationship between the current document and the one the Href of the tag leads to. With no value of its own, a tag opening in a new browsing context gets rel="noopener" automatically. |
| Reversed | `bool` | false | Reverses the direction flow of the content of the tag: the icon, the label, the trailing SecondaryIcon, the two templates and the dismiss button all swap ends with it. |
| SecondaryIcon | `BitIconInfo?` | null | The trailing icon of the tag, rendered after the label and before the dismiss button, using custom CSS classes for external icon libraries. Takes precedence over SecondaryIconName when both are set. |
| SecondaryIconName | `string?` | null | The name of the trailing icon of the tag, from the built-in Fluent UI icons. It is rendered after the label and before the dismiss button, inside whatever the tag became, and it mirrors with the rest of the row when the tag is Reversed. |
| SecondaryText | `string?` | null | The secondary text of the tag, rendered under the Text in a quieter type. |
| Selected | `bool` | false | Marks the tag as selected, which paints it in its selected colors and shows a checkmark in front of its content. Binding it - or setting OnChange - turns the tag into a toggle button reporting aria-pressed; a tag that is a link reports aria-current instead. |
| SelectedChanged | `EventCallback<bool>` | | Callback for when the Selected value changes, which is what binding Selected assigns. |
| SelectedIcon | `BitIconInfo?` | null | The icon of the checkmark a selected tag shows, using custom CSS classes for external icon libraries. Takes precedence over SelectedIconName when both are set. |
| SelectedIconName | `string?` | null | The name of the icon of the checkmark a selected tag shows, from the built-in Fluent UI icons. Defaults to Accept when not set. |
| Shape | `BitTagShape?` | null | The corner shape of the tag. |
| Size | `BitSize?` | null | The size of the tag. |
| StopPropagation | `bool` | false | Stops the click of the tag from bubbling any further up the DOM, for a tag sitting inside something else that reacts to a click. |
| Styles | `BitTagClassStyles?` | null | Custom CSS styles for different parts of the tag. |
| SuffixTemplate | `RenderFragment?` | null | Custom markup rendered at the end of the tag, after the trailing SecondaryIcon and before the dismiss button. The mirror of the PrefixTemplate, and subject to the same rules. |
| Target | `string?` | null | The browsing context the Href of the tag is opened in, for example _blank. |
| Text | `string?` | null | The text of the tag. |
| Title | `string?` | null | The tooltip to show when the mouse is placed on the tag, which is what spells out whatever a NoWrap ellipsis has cut off. |
| Variant | `BitVariant?` | null | The visual variant of the tag. |
| 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. |
| 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. |
| IsEnabled | `bool` | true | Gets or sets a value indicating whether the component is enabled and can respond to user interaction. |
| 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 |
| :--- | :--- | :------------ | :---------- |
| FocusAsync | `ValueTask` | | Gives the keyboard focus to the tag: the anchor or the button it becomes while it is a control, the dismiss button of a tag that has only that, and the root element otherwise. |
| 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
### BitNavAriaCurrent Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Page | 0 | Represents the current page within a set of pages. |
| Step | 1 | Represents the current step within a process. |
| Location | 2 | Represents the current location within an environment or context. |
| Date | 3 | Represents the current date within a collection of dates. |
| Time | 4 | Represents the current time within a set of times. |
| True | 5 | Represents the current item within a set, without saying which kind of set it is. |
### 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. |
### BitTagShape Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Rounded | 0 | Takes the chip corner of the current theme, which is a pill in Cupertino and a small radius in Fluent and Material. |
| Circular | 1 | Rounds the corner fully, so the tag is always a pill whatever the theme says. |
| Square | 2 | Drops the corner altogether, so the tag is a rectangle. |
### 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. |
### 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
### 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, which is the anchor or the button the tag becomes while it is a link or a control, and a plain 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. |
## Examples
\n**Basic**:
```razor
Reset
```
```csharp
private List dismissibleTags = ["Design", "Research", "Docs"];
private void ResetDismissibleTags()
{
dismissibleTags = ["Design", "Research", "Docs"];
}
```
\n**Click**:
```razor
selectedFilters = ["In progress"];
private void ToggleFilter(string filter, bool selected)
{
if (selected)
{
if (selectedFilters.Contains(filter) is false)
{
selectedFilters.Add(filter);
}
}
else
{
selectedFilters.Remove(filter);
}
}
```
\n**Template**:
```razor
Custom content
Alex (owner)
Status
AP
24
```
\n**Truncation**:
```razor
Reset
Focus it
```
```csharp
private List focusTags = ["Design", "Research", "Docs"];
private readonly Dictionary focusTagRefs = [];
private async Task DismissFocusTag(string tag)
{
var index = focusTags.IndexOf(tag);
focusTags.Remove(tag);
focusTagRefs.Remove(tag);
if (focusTags.Count == 0) return;
// the tag that took its place, or the last one when the end of the list was removed
var next = focusTags[Math.Min(index, focusTags.Count - 1)];
if (focusTagRefs.TryGetValue(next, out var nextRef))
{
await nextRef.FocusAsync();
}
}
private void ResetFocusTags()
{
focusTags = ["Design", "Research", "Docs"];
}
private BitTag? plainFocusTag;
```
\n**Accessibility**:
```razor
The card counts every click that reaches it. The second tag stops its own.
Clicked @clickCount times, dismissed @dismissCount times, card clicked @cardClickCount times.
```
```csharp
private int clickCount;
private int dismissCount;
private int cardClickCount;
```
\n**Link**:
```razor
Selected: @(selectedFilters.Count == 0 ? "none" : string.Join(", ", selectedFilters))
```
```csharp
private bool isPinned;
private bool isStarred = true;
private bool allowSelectionChange;
private readonly string[] filters = ["Open", "In progress", "Done"];
private readonly ListDisabled: