TagsInput

Type a word and press Enter: it becomes a chip in front of the input, and its dismiss button takes it back off. ReadOnly keeps the tags visible and navigable while refusing every change to them, so the dismiss buttons are not rendered at all, and IsEnabled="false" dims the whole field along with the tags in it.

Label renders the caption above the field and ties it to the input, so clicking it puts the caret in there and screen readers announce it with the field. LabelTemplate replaces the text with markup of your own when a plain string is not enough. Combined with the inherited Required, the label carries the asterisk that marks the field as mandatory.

Description renders a hint under the field, which the input references through its aria-describedby attribute, so it is announced along with the field rather than only being drawn. It is where the rules of the field belong: the accepted format, the number of tags allowed, the separator that splits them. DescriptionTemplate takes markup instead of a string, and is referenced exactly the same way.

Placeholder is the hint shown while the list is still empty. Once there is at least one tag it would only compete with them for the width of the field, so it is dropped - unless a TagsPlaceholder is given, which is what keeps the invitation to add another one visible without repeating the whole sentence.

Variant decides how much of a frame the field carries: Outline (the default) draws a full rule around it, Fill paints it with a surface color and drops the rule, and Text keeps only an underline, for a field that should not outweigh the ones around it. NoBorder removes the frame altogether, for a field sitting on a surface that already provides one. It is the frame of the field alone; how the tags in it are painted is the TagVariant.

TagVariant decides how much of the Color the tags themselves are painted with: Fill (the default) fills every chip with it, the way a BitTag is filled, Outline leaves the chip unfilled and draws the color as its rule and its text, and Text keeps only the text in it, for tags that should not outweigh the field holding them. It is independent of the Variant, which is about the frame of the field rather than the tags in it, so the two combine freely.

By default the Enter key is the only thing that turns the typed text into a tag. Separators adds characters that do the same: typing one of them commits whatever stands before it, and the character itself never reaches the input. A separator is any string at all - a single character such as a comma or a space, or a longer one such as ", ". The very same separators split a paste, so a comma separated list copied out of a spreadsheet or a mail client arrives as a whole row of tags in one go - each piece of it going through the same validation, so the ones that are refused are reported while the rest are still added. A pasted text spread over several lines is joined over the first separator on its way in, since a single line field would otherwise drop the line breaks and leave one run-on tag behind.

Suggestions offers a set of known values while the user types, through the suggestion list the browser itself renders for a datalist - which is what keeps it reachable, positioned and announced on every platform without a popup of our own. Picking one only fills the input; it is the usual Enter (or a separator) that turns it into a tag, so every rule of the field still applies to it. The values already in the list are left out of the suggestions, unless Duplicates allows them back in, and so are all of them once the MaxTags ceiling leaves nothing to add. A datalist suggests rather than restricts, so free text is still accepted next to it; RestrictToSuggestions is what turns the suggestions into the whole of what the field accepts, rejecting anything else with the NotSuggested reason. What counts as one of the suggestions is decided by Comparison, and the tag that is stored is the suggestion rather than the spelling it was typed with - so with an OrdinalIgnoreCase comparison, typing BLAZOR adds blazor, and a list that has to be grouped or looked up later never holds two spellings of one value.

A catalogue of known values is written into the page in full, and rebuilt on every keystroke, so MaxSuggestions caps how many of them are offered at once: beyond it only the values holding what is being typed are kept, and only as many of those as it allows. It changes nothing about what the user is actually shown - the browser filters the list it is handed all over again - only about how much of a catalogue of thousands ever reaches the page.

MaxTags caps how many tags the list may hold. Once the ceiling is reached every further tag is rejected with the MaxTags reason, which the OnInvalid callback receives - so the field can say why nothing happened instead of appearing to ignore the Enter key. A paste that would overflow the cap stops there rather than being rejected as a whole.

MaxLength caps the number of characters of each individual tag. It is a truncation rather than a rejection: the input stops accepting characters beyond it, and a pasted value longer than it is cut down to size instead of being thrown away - which matters for a paste, where throwing the twelfth character away is far better than throwing the whole list away. The little input that replaces a tag while it is corrected in place carries the cap natively, since there the limit of a tag is the limit of the whole field. MinLength works the other way round and does reject: a tag shorter than it never enters the list, and the rejection is reported with the MinLength reason. Both of them count the text after the trimming and the Transformer, so they measure exactly what would be added.

Pattern is a regular expression that every tag has to match; an expression that cannot be compiled is ignored rather than breaking the field, and a match that runs away is timed out and treated as a failure. Validator covers what an expression cannot express - a lookup in a list of allowed values, a checksum, a rule that depends on the other tags - by taking a predicate instead. Both run after the trimming and the transformation, so they see exactly the text that would be added, and both report their rejection through OnInvalid.

Transformer normalizes the text of a tag before anything else is done with it, which is what keeps a list consistent whichever way its entries were typed: lower casing them, stripping a leading #, collapsing the whitespace inside them. It runs before the length, pattern, validator and duplicate checks, so all of them see the normalized text - which means #Blazor, blazor and BLAZOR all collapse into the same tag and the second of them is refused as a duplicate. An exception thrown out of it leaves the text untouched rather than breaking the field.

A tag that is already in the list is refused by default, and the refusal is reported through OnTagExists as well as through OnInvalid. Duplicates lifts that rule for the lists where repetition means something. Which tags count as the same one is decided by Comparison: it is Ordinal by default, so Blazor and blazor are two different tags, while OrdinalIgnoreCase makes them one.

EditableTags lets a tag be corrected in place instead of having to be removed and typed again: double click a chip, or press Enter or F2 on the focused one, and it turns into a little input with its text selected. Enter commits the new text, Escape puts the old one back, and leaving the input commits it too. The text goes through the very same trimming, transformation and validation as a tag being added - except that the tag is not a duplicate of itself and the MaxTags ceiling cannot be reached, since the list does not grow. Committing an empty text removes the tag, and OnEdit receives the old and the new text and can call the change off. The Enter that commits the correction is held back from the form around the field exactly as the one that adds a tag is, and an input method composing a character keeps it as well, so a correction is never committed half way through a word.

ShowClearButton renders a button at the end of the field that empties the whole list along with the text left in the input, and raises OnClear with the tags it removed. It is not rendered while the field is read-only, disabled or already empty, and it stays out of the tab order - the Escape key pressed on the input being its keyboard equivalent. Escape takes back what is being typed before it takes anything else, though: while there is text in the input it only clears that text, and it is the second press, on the now empty input, that empties the list - since throwing a whole list of tags away over a half typed word is not an undo but a loss. OnBeforeClear runs first, whichever of the three emptied the field, and receives the whole list along with a Cancel flag - which is where a confirmation belongs, emptying a list of fifty tags by accident being exactly the mistake that is worth one. Pressing the button takes the button itself away with everything else, so the caret is handed back to the input rather than being dropped on the page; a clear that was called off leaves both exactly where they were.

ShowCounter draws the number of tags under the field, at the end of the line the Description sits on, as a plain count or as count / MaxTags when there is a ceiling to reach. It is drawn rather than announced - the list of chips is what a screen reader counts, and every addition and removal is already spoken by the live region.

The chips are a single stop of the tab order rather than one per tag, which the arrow keys then walk through: Left and Right (swapped in a right-to-left direction) move between them, Home and End jump to the two ends, Delete and Backspace remove the focused one and hand the focus to its neighbour, Enter and F2 open the inline edit when EditableTags is on, Alt with the arrows moves the tag when AllowReorder is, and Escape goes back to the input. Every one of those keys carries a browser default that is held back for it - Home and End would scroll the page away, Alt with an arrow would walk the whole document back through the history - so a gesture of the field never turns into a gesture of the browser. From the input, Backspace on an empty field removes the last tag (which NoBackspaceRemove turns off, and which BackspaceEditsLastTag turns from a removal into a correction, putting the text of that tag back into the input to be fixed and confirmed again rather than letting it simply disappear), and the arrow pointing backwards walks into the last chip. Tab commits the text left in the input instead of leaving it behind - unless NoAddOnTab is set - while Shift+Tab always walks straight out, so the field is never a trap. Losing the focus commits the text as well, which NoAddOnBlur turns off and ClearOnBlur turns into a discard, so a half typed word is not found again hours later in a field the user believes they finished with. Escape takes back the text being typed, and only empties the list on a second press, once there is nothing left to take back and ShowClearButton is on.

None of that is visible on a chip that looks like nothing but a word, so once the inline edit or the reordering is on, each tag is announced with a sentence saying which keys it answers to - TagAriaDescription being what replaces, localizes or silences it. Each chip also carries its own position in the whole list, so "the third of six" stays true even where MaxDisplayedTags has folded the other three away. And while an input method is composing a character (Chinese, Japanese, Korean), the Enter that picks a candidate out of the suggestion window is not treated as a confirmation - neither in the input nor in the inline edit - so a tag is never cut in half by it.

AllowReorder lets a tag be moved within the list two equal ways. With a pointer, a chip can be picked up and dropped onto the one whose position it should take: the chip being carried is faded out and the one under the pointer is outlined, so the landing place is visible before the button is let go of. Without a pointer, focus a chip and hold Alt while pressing the left or right arrow to walk it one position at a time, or Alt+Home and Alt+End to send it to either end - which is what keeps the reordering usable on a touch screen and with a screen reader, where a drag is not. Either way the focus travels with the tag, so several steps can be taken in a row, and each move is announced along with the position the tag landed on. In a right-to-left direction the arrows are mirrored, exactly as they are for the plain navigation, and the browser's own Alt+arrow history navigation is held back so that reordering a tag never leaves the page.

OnReorder reports each move with the tag and the two positions it went between, which is what tells a consumer which tag moved and where to - the bound value alone would have to be diffed against its previous state to find that out. The order of the tags is part of the value, so a move is a change like any other: it is written back through @bind-Value and reported through OnChange as well.

TagTemplate replaces the text of every chip with markup of your own, the tag itself being the context. The chip around it - its background, its focus ring and its dismiss button - is still provided by the component, so a template only has to describe what goes inside.

The value is the list of tags itself, bound two ways with @bind-Value. DefaultValue seeds an uncontrolled field, the one that is read through the OnChange callback rather than through a bound property. Note that removing the last tag leaves the value at null rather than at an empty list, which is what makes a plain [Required] annotation catch an empty field.

OnBeforeAdd and OnBeforeRemove run before the list is changed and can call the change off by setting args.Cancel, which is the hook for a confirmation or for a rule that lives on the server. OnAdd receives every tag added in one go (a paste adds several of them at once), OnRemove the one that was taken off, OnInvalid the one that was refused along with the rule that refused it, and OnInput the text of the input as it is typed - which is what an external suggestion list is driven by. OnInput also reports the emptying the component does itself, when the text becomes a tag or the field is cleared, so a suggestion list of your own is never left filtering on a word that is already a chip. OnFocusIn, OnFocusOut and OnKeyDown report the plain input events on top of them.

The component can be driven from the outside as well: AddTagAsync and AddTagsAsync add through exactly the same pipeline as typing does (trimming, transformation, every validation rule and every callback), RemoveTagAsync and RemoveTagAtAsync take one off, MoveTagAsync moves one to another position exactly as a drag does - raising OnReorder with it, and without needing AllowReorder, since that parameter is what offers the gesture to the user rather than what permits the list to be reordered - EditTagAsync opens the inline edit of one (which does need EditableTags), SetInputTextAsync writes the text of the input - which is what fills the field from a suggestion list of your own driven by OnInput, and what empties it again once the pick has been turned into a tag - Clear empties the whole list, and FocusAsync puts the caret in the input. All of them do nothing while the field is disabled or read-only, and all of them go through the callbacks, the announcements and the validation that the equivalent gesture does, so nothing reaches the value by a back door.

Enter is the key that confirms a tag, so it is held back from submitting the form around the field - which would otherwise post the form on the very keystroke meant to add a tag. CancelConfirmKeysOnEmpty hands it back once there is nothing left to confirm, so a field whose tags are already in place submits with Enter like any other input. Setting Name posts the whole list as a single field of a plain (non-EditForm) HTML form, the tags joined by the first separator, rather than posting whatever text happened to be left in the input.

Inside an EditForm the field takes part in the validation like any other input: it reports its changes to the EditContext, paints the error state, marks its input with aria-invalid and turns its description red. The value is the list itself, so the annotations that apply to it are the collection ones - [Required] catching the null of an empty field and [MinLength]/[MaxLength] counting its entries.

A field that collects dozens of tags grows into a wall of chips that pushes everything below it off the screen. MaxDisplayedTags draws only the first few of them and folds the rest away behind a chip that says how many are left, which unfolds the list and folds it back again - so a tag that is not drawn is never a tag that cannot be reached, neither with the pointer nor with the keyboard, where the chip is a tab stop of its own. Only how much of the list is drawn changes: the value keeps every one of its tags, the counter keeps counting all of them, and the form keeps posting them. MoreTagsFormat and LessTagsText are what the two labels of the chip are written and localized with, and MoreTagsAriaLabelFormat what it is announced as - since "+3" read out on its own says nothing about what pressing it would do.

Nothing about a chip appearing, disappearing or changing place reaches a screen reader on its own - the list sits away from the caret the user is typing at - so the component says every one of those out loud through a polite live region: AddedAnnouncementFormat, AddedManyAnnouncementFormat, RemovedAnnouncementFormat, ClearedAnnouncementFormat, EditedAnnouncementFormat, MovedAnnouncementFormat and InvalidAnnouncementFormat. Most of them take {0} for the tag they are about - the move also taking {1} for the position it landed on and {2} for how many tags there are - and an empty string keeps that particular event silent. The two that stand for a whole batch count instead of naming: a pasted list and a cleared field take {0} as the number of tags, since reading fifty names out is not a confirmation but a wall, and the tags themselves are in the list to be walked through anyway.

The names of the parts follow the same idea: TagsAriaLabel names the list the chips form, TagAriaDescription is the sentence telling what the keyboard can do with the one just reached, DismissAriaLabelFormat and DismissTitle name the dismiss button of each tag, EditAriaLabelFormat the little input that replaces a tag while it is corrected, and ClearButtonAriaLabel the button that empties the whole field. Every one of them is a plain string, which is what makes the component translatable without a single line of CSS or markup of your own.

Prefix and Suffix draw a short text inside the field, at its start and at its end, which is not part of the value: the To: of a recipients field, the unit a list of measurements is in. The prefix sits in front of the chips and the suffix after everything else, the clear button included, so it stays at the very end however much of the line the tags have taken. PrefixTemplate and SuffixTemplate take markup instead of a string, for an icon or a badge.

Neither of them ever reaches the value, and neither is announced with the field, so the meaning they carry has to be in the Label as well: a screen reader reading "Tags, edit" out of a field whose prefix says To: would otherwise have no idea what the tags are.

Classes and Styles dress every chip alike, and TagTemplate only changes what is drawn inside one. GetTagClass and GetTagStyle are what tell one chip apart from the next: each of them receives a tag and returns the classes or the declarations that this particular chip should carry on top of the shared ones - the address that is not in the address book drawn in red, the value that came from a saved filter drawn in grey, the tag that is over budget outlined. They are called for every drawn tag on every render, so they belong to a lookup rather than to a computation, and an exception thrown out of one of them leaves that chip looking like all the others instead of breaking the field.

Color picks the color role the component carries. The tags are painted with it, as much of them as the TagVariant asks for, and so are the border and the focus ring of the focused field, so the color is visible at rest rather than only while the field is focused. The error state of a failing validation always wins over it on the field, which keeps an invalid field recognizable whatever its color is.

The dismiss button of each tag and the clear button of the field both take their icon either from the built-in Fluent UI set, through DismissIconName and ClearButtonIconName, or from any external icon library through DismissIcon and ClearButtonIcon, which take a BitIconInfo built by BitIconInfo.Fa (FontAwesome), BitIconInfo.Bi (Bootstrap Icons) or BitIconInfo.Css (any CSS classes at all). The BitIconInfo wins over the name when both are given.

Size scales the field, the chips and the text inside them together, so the whole thing stays proportionate at every size. Pick the one that matches the density of the surrounding form: the large size suits a standalone editor, the small one a filter tucked into a toolbar.

Style and Class reach the root element only, while Styles and Classes reach every part of the component by name: the root, the label, the description, the counter, the input container, the prefix and the suffix, the wrapper of the tags, each tag and its text, the dismiss button and its icon, the chip that folds the tags away, the input, the little input that replaces a tag while it is corrected, and the clear button and its icon - plus the two state slots Focused (the field while its input has the focus) and FocusedTag (the chip the arrow keys are currently on).

In a right-to-left direction the chips are laid out from right to left and the arrow keys swap along with them, so the key pointing at the visual left still walks towards the tag drawn there. The value itself keeps its logical order: the first chip is always the first tag of the list.