# TagsInput
## Description
A tags input (TagsInput) provides an input field for adding and managing tags (keywords).
## Parameters
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| AutoFocus | `bool` | false | Whether the input should receive focus on first render. |
| CancelConfirmKeysOnEmpty | `bool` | false | When true, pressing Enter while the input is empty does not suppress the event, allowing it to propagate (e.g., to submit a parent form). |
| Classes | `BitTagsInputClassStyles?` | null | Custom CSS classes for different parts of the tags input. |
| DismissIcon | `BitIconInfo?` | null | Gets or sets the icon for the dismiss button using custom CSS classes for external icon libraries. Takes precedence over DismissIconName when both are set. |
| DismissIconName | `string?` | Cancel | Gets or sets the name of the icon for the dismiss button from the built-in Fluent UI icons. |
| Duplicates | `bool` | false | Whether duplicate tags are allowed. |
| Label | `string?` | null | The label displayed above the input. |
| LabelTemplate | `RenderFragment?` | null | A custom template for the label. |
| MaxLength | `int` | 0 | The maximum number of characters allowed for each individual tag. 0 means no limit. |
| MaxTags | `int` | 0 | The maximum number of tags allowed. 0 means no limit. |
| NoBorder | `bool` | false | Removes the default border of the tags input. |
| OnBeforeAdd | `EventCallback<BitTagsInputBeforeArgs>` | | Callback invoked before a tag is added. Set args.Cancel = true to cancel the add. |
| OnBeforeRemove | `EventCallback<BitTagsInputBeforeArgs>` | | Callback invoked before a tag is removed. Set args.Cancel = true to cancel the remove. |
| OnAdd | `EventCallback<IReadOnlyList<string>>` | | Callback for when one or more tags are added. Receives the list of all newly added tags. |
| OnTagExists | `EventCallback<string>` | | Callback fired when a duplicate tag is attempted and Duplicates is false. |
| OnFocusIn | `EventCallback<FocusEventArgs>` | | Callback for when the input receives focus. |
| OnFocusOut | `EventCallback<FocusEventArgs>` | | Callback for when the input loses focus. |
| OnRemove | `EventCallback<string>` | | Callback for when a tag is removed. |
| Placeholder | `string?` | null | Placeholder text for the input. Hidden when tags are present. |
| Separators | `IEnumerable<string>?` | null | The character(s) used to separate tags when typing. Also used to split pasted text into multiple tags. Defaults to Enter key only. |
| Styles | `BitTagsInputClassStyles?` | null | Custom CSS styles for different parts of the tags input. |
| TagTemplate | `RenderFragment<string>?` | null | A custom template for rendering each tag. |
| DefaultValue | `TValue?` | null | The default value of the input to be used in uncontrolled mode (i.e. when the Value is not bound), typically used alongside the OnChange callback. |
| DisplayName | `string?` | null | Gets or sets the display name for this field. |
| InputHtmlAttributes | `IReadOnlyDictionary<string, object>?` | null | Gets or sets a collection of additional attributes that will be applied to the created element. |
| Name | `string?` | null | Gets or sets the name of the element. Allows access by name from the associated form. |
| NoValidate | `bool` | false | Disables the validation of the input. |
| OnChange | `EventCallback<TValue?>` | | Callback for when the input value changes. |
| ReadOnly | `bool` | false | Makes the input read-only. |
| Required | `bool` | false | Makes the input required. |
| Value | `TValue?` | null | Gets or sets the value of the input. This should be used with two-way binding. |
| 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. |
| 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 |
| :--- | :--- | :------------ | :---------- |
| InputElement | `ElementReference` | | The ElementReference to the input element of the BitTagsInput. |
| FocusAsync | `ValueTask` | | Gives focus to the input element of the BitTagsInput. |
| Clear | `Task` | | Removes all tags. |
| InputElement | `ElementReference` | | The ElementReference of the input element. |
| FocusAsync() | `() => ValueTask` | | Gives focus to the input element. |
| FocusAsync(bool preventScroll) | `(bool preventScroll) => ValueTask` | | Gives focus to the input element. |
| 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
### 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
### BitTagsInputBeforeArgs Properties
Arguments passed to the OnBeforeAdd and OnBeforeRemove callbacks.
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Tag | `string` | string.Empty | The tag text being added or removed. |
| Cancel | `bool` | false | Set to true to cancel the add or remove operation. |
### BitTagsInputClassStyles Properties
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Root | `string?` | null | Custom CSS classes/styles for the root element of the tags input. |
| Focused | `string?` | null | Custom CSS classes/styles for the focus state of the tags input. |
| Label | `string?` | null | Custom CSS classes/styles for the label of the tags input. |
| InputContainer | `string?` | null | Custom CSS classes/styles for the input container of the tags input. |
| Tag | `string?` | null | Custom CSS classes/styles for each tag element. |
| TagText | `string?` | null | Custom CSS classes/styles for the tag text. |
| DismissButton | `string?` | null | Custom CSS classes/styles for the dismiss button of each tag. |
| DismissIcon | `string?` | null | Custom CSS classes/styles for the dismiss icon of each tag. |
| Input | `string?` | null | Custom CSS classes/styles for the text input element. |
### 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
Custom label
```
\n**NoBorder**:
```razor
? boundTags;
private ICollection? eventTags;
private string? addedTag;
private string? removedTag;
```
\n**Duplicates**:
```razor
```
\n**MaxLength**:
```razor
```
\n**Validation**:
```razor
Submit
```
```csharp
private readonly ValidationTagsInputModel validationModel = new();
private void HandleValidSubmit() { }
public class ValidationTagsInputModel
{
[Required(ErrorMessage = "At least one tag is required.")]
[MinLength(1, ErrorMessage = "At least one tag is required.")]
public ICollection? Tags { get; set; }
}
```
\n**Style & Class**:
```razor
Tags: @(boundTags is not null ? string.Join(", ", boundTags) : "null")
Added: @addedTag
Removed: @removedTag
```
```csharp
private ICollectionStatus: @eventsStatus
@if (tagExistsMsg is not null)
{
@tagExistsMsg
}
```
```csharp
private string? eventsStatus;
private string? tagExistsMsg;
private void HandleTagExists(string tag)
{
tagExistsMsg = $"Tag '{tag}' already exists!";
}
private void HandleBeforeAdd(BitTagsInputBeforeArgs args)
{
if (args.Tag.Equals("block", StringComparison.OrdinalIgnoreCase))
{
args.Cancel = true;
eventsStatus = $"Adding '{args.Tag}' was blocked by OnBeforeAdd.";
}
else
{
eventsStatus = $"Tag '{args.Tag}' added.";
}
tagExistsMsg = null;
}
private void HandleBeforeRemove(BitTagsInputBeforeArgs args)
{
eventsStatus = $"Removing '{args.Tag}'.";
tagExistsMsg = null;
}
```
\n**CancelConfirmKeysOnEmpty**:
```razor
Form submitted: @cancelFormSubmitted