TagsInput

Type a word and press Enter: it becomes a chip, and its dismiss button takes it back off. Placeholder is the hint shown while the list is still empty; once there is a tag it would only compete with the chips for the width of the field, so it is dropped unless a TagsPlaceholder keeps the invitation visible. ReadOnly keeps the tags visible and navigable while refusing every change, and Disabled dims the whole field along with them.

Label renders the caption above the field and ties it to the input, so clicking it puts the caret in there. With the inherited Required it carries the asterisk that marks the field as mandatory. Description renders a hint under the field which the input references through aria-describedby, so it is announced along with the field rather than only drawn - which is where the rules of the field belong. LabelTemplate and DescriptionTemplate take markup instead of a string.

Variant decides how much of a frame the field carries - Outline (the default), Fill or only an underline with Text - and NoBorder removes it altogether. TagVariant decides how much of the color the chips are painted with, exactly as a BitTag is. The two are independent, so they combine freely.

By default only Enter turns the typed text into a tag. Separators adds characters that do the same: typing one commits what stands before it, and the character itself never reaches the input. A separator is any string - a comma, a space, or something longer such as ", ". The same separators split a paste, so a comma separated list arrives as a whole row of tags, each piece going through the same validation. A paste spread over several lines is joined over the first separator on its way in, so a column copied out of a spreadsheet does not land as one run-on tag.

Suggestions offers known values while the user types, through the list the browser itself renders for a datalist - reachable, positioned and announced on every platform without a popup of our own. Picking one only fills the input; the usual Enter turns it into a tag, so every rule still applies. Values already in the list are left out, and so are all of them once MaxTags leaves nothing to add. A datalist suggests rather than restricts: RestrictToSuggestions is what makes them the only accepted values, rejecting anything else with the NotSuggested reason. What counts as one of them is decided by Comparison, and the tag that is stored is the suggestion rather than the spelling it was typed with, so a list to be grouped later never holds two spellings of one value. MaxSuggestions caps how many are written into the page at once - beyond it only the values holding what is being typed are kept, matched without regard to case the way the browser filters the list it is handed, so what the user is shown does not change. Where the catalogue is fetched rather than held, OnInput is what triggers the fetch and IsLoading draws the spinner that says the field is waiting - an indeterminate progressbar, so a screen reader hears the wait instead of missing it. DebounceTime waits for the typing to stop before raising it, which turns a request per keystroke into a request per word (ThrottleTime spaces them out instead, for a list that should keep up while the word is still being typed). Only the callback waits: the text itself is tracked as it is typed, so the tag Enter commits is never a keystroke behind, and the emptying that follows a committed tag is reported at once, taking the pending call down with it.

MaxTags caps how many tags the list may hold; beyond it every tag is rejected with the MaxTags reason, which OnInvalid receives along with the tag - 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 refused whole. MaxLength caps the characters of each tag and truncates rather than rejects - throwing the twelfth character away beats throwing a pasted list away - while MinLength rejects what is too short. Both count the text after trimming and transformation, so they measure exactly what would be added. ShowCounter draws the number of tags under the field, as a plain count or as count / MaxTags.

Transformer normalizes the text before anything else is done with it - lower casing, stripping a leading #, collapsing whitespace - so every rule below sees the normalized text and it is the normalized text that is stored. Pattern is a regular expression every tag has to match (an expression that cannot be compiled is ignored rather than breaking the field, and a runaway match is timed out and treated as a failure); Validator covers what an expression cannot - a lookup, a checksum, a rule depending on the other tags. A tag already in the list is refused by default and reported through OnTagExists; Duplicates lifts that, and Comparison decides which tags count as the same one. Every refusal reaches OnInvalid with the rule that caused it.

A refusal is never silent. ShowInvalidMessage draws why under the field, where the helper text stands - the same sentence screen readers are given, naming the limit the rule was built on ("A tag must be at least 3 characters.") rather than leaving the user to guess; a red rule alone is a message half the readers of a page never get. GetInvalidMessage rewrites that sentence for wording of your own and for localization, and InvalidAnnouncementFormat writes the frame it sits in ({0} the tag, {1} the reason). Alongside it the field wears its invalid color - and says so through aria-invalid - until the next keystroke answers it, and a tag refused as a duplicate marks the chip already in the list that it collided with, since "you already have this one" is only an answer if it says which one. NoInvalidHighlight turns that mark off, and OnInvalid (with OnTagExists for the duplicate alone) hands the refusal to a report of your own.

EditableTags lets a tag be corrected in place instead of being 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 - carrying the same InputMode, EnterKeyHint and SpellCheck as the field, since those belong to the values it collects rather than to the one box they are typed into. Enter commits, Escape puts the old text back, and leaving the input commits too. The text goes through the same trimming, transformation and validation as a tag being added - except that the tag is not a duplicate of itself and the ceiling cannot be reached, since the list does not grow. A correction those rules turn down is handed back in the still open input, caret at its end, rather than being thrown away with the chip snapping back: an error is the one moment a field must not lose what was just entered. Committing an empty text removes the tag, and OnEdit receives the old and the new text and can call the change off.

AllowReorder lets a tag be moved three equal ways, one for each kind of user. Drag a chip onto the one whose position it should take: the carried chip fades and the one under the pointer is outlined, so the landing place is visible before the button is let go of. Tap the handle the chip grows at its start, then the tag whose place it should take - two taps rather than a drag, for every pointer that cannot drag at all: a touch screen, a switch, a head pointer. A second tap on the handle, on the lifted chip, on the field around it, or the Escape key puts it back down. From the keyboard, hold Alt with the arrow keys to walk the focused chip one position at a time, or Alt+Home / Alt+End to send it to either end. Whichever it was, the focus travels with the tag and the move is announced. ReorderIconName, ReorderTitle, ReorderAriaLabelFormat and ReorderDropAriaLabelFormat write the handle, and PickedUpAnnouncementFormat and PutBackAnnouncementFormat what it says out loud. OnReorder reports the tag and the two positions, which is what says which chip moved without diffing the list; the order is part of the value, so the move is written back through @bind-Value as well.

MaxDisplayedTags draws only the first few chips and folds the rest behind one saying how many are left, which unfolds the list and folds it back - so a tag that is not drawn is never a tag that cannot be reached, with the pointer or with the keyboard, where the chip is a tab stop of its own. Only how much is drawn changes: the value keeps every tag, the counter counts all of them, and the form posts them. MoreTagsFormat and LessTagsText write its two labels, MoreTagsAriaLabelFormat what it is announced as - "+3" read out alone says nothing about what pressing it would do.

ShowClearButton renders a button at the end of the field that empties the whole list along with the text in the input, and raises OnClear with what it removed. It is not rendered while the field is read-only, disabled or already empty, and it stays out of the tab order - Escape on the input is its keyboard equivalent. Escape takes back what is being typed first, though: it is the second press, on the now empty input, that empties the list. OnBeforeClear runs first whichever of the three emptied the field and can call it off, which is where a confirmation belongs. Pressing the button takes the button away with everything else, so the caret is handed back to the input rather than dropped on the page. NoClearOnEscape hands the key back to whatever surrounds the field, for a form inside a modal or a callout where dismissing that is what the user means by pressing it.

CanRemoveTag decides which tags the user may take off the list, for the values a field holds but does not let go of: the owner among the editors of a document, the tag a saved filter is built on. A tag it turns down is drawn without a dismiss button, ignores Delete and Backspace, is left alone by the Backspace pressed on the empty input, and stays behind when the field is cleared - so clearing empties the field of everything it can be emptied of, and a field holding nothing else does not render a clear button at all. It is still editable and still movable, since neither takes the tag away, and the sentence announced after a fixed chip says so rather than promising a removal that does nothing. It governs what the user may do, not what you may: RemoveTagAsync names a tag outright and takes it off regardless.

The chips are a single stop of the tab order rather than one per tag. Left and Right (swapped in RTL) move between them, Home and End jump to the ends, Delete and Backspace remove the focused one and hand the focus to its neighbour, Enter and F2 open the inline edit, Alt with the arrows moves the tag, and Escape goes back to the input. Every one of those keys carries a browser default that is held back for it, so a gesture of the field never turns into a gesture of the browser. NoClearOnEscape leaves Escape alone altogether, for a field inside a surface that closes on it.

From the input, Backspace on an empty field removes the last tag - NoBackspaceRemove turns that off and BackspaceEditsLastTag turns it into a correction, putting the tag's text back into the input instead of letting it disappear - and the backwards arrow walks into the last chip. Tab commits the text left in the input unless NoAddOnTab is set, while Shift+Tab always walks straight out, so the field is never a trap. Losing the focus commits too, which NoAddOnBlur turns off and ClearOnBlur turns into a discard. While an input method is composing a character the Enter that picks a candidate is not treated as a confirmation, so a tag is never cut in half by it.

InputMode and EnterKeyHint decide the virtual keyboard a phone opens and the label on its return key; SpellCheck turns the red underline back on for a field that collects words rather than identifiers, and AutoComplete hands the browser's own autofill back where the field collects values it knows about.

A chip appearing, disappearing or changing place reaches no screen reader on its own - the list sits away from the caret - so the component says each of them out loud through a polite live region: AddedAnnouncementFormat, AddedManyAnnouncementFormat, RemovedAnnouncementFormat, ClearedAnnouncementFormat, EditedAnnouncementFormat, MovedAnnouncementFormat, PickedUpAnnouncementFormat, PutBackAnnouncementFormat and InvalidAnnouncementFormat. Most take {0} for the tag - the move also {1} for the position it landed on and {2} for how many tags there are, the refusal {1} for why it was turned down - and an empty string keeps that event silent. The two standing for a batch count instead of naming: reading fifty names out is not a confirmation but a wall, and the tags are in the list to be walked through anyway.

The list itself sits away from the caret, so a reader landing in a field that already holds tags would otherwise be told only that the input is empty: the input describes itself with how many there are - "3 of 5 tags" where MaxTags sets a ceiling - which TagCountAriaDescriptionFormat writes. It is referenced rather than announced, so it is read on arriving and never while the field is being typed into.

The names of the parts follow the same idea: TagsAriaLabel names the list, TagAriaDescription is the sentence telling what the keyboard can do with the chip just reached (built from the gestures the field was actually given, and left out when there are none), DismissAriaLabelFormat and DismissTitle name the dismiss button, ReorderAriaLabelFormat, ReorderDropAriaLabelFormat and ReorderTitle the reorder handle, EditAriaLabelFormat the little edit input, and ClearButtonAriaLabel the button that empties the field. Each chip also carries its own position in the whole list, so "the third of six" stays true where MaxDisplayedTags folded the rest away.

One thing a chip cannot give on its own is a 24 CSS-pixel pointer target (WCAG 2.2, SC 2.5.8): the dismiss button and the reorder handle take the full height of the chip and a pad on either side of the glyph, which is all a chip as tall as a line of text has to give. Where that minimum has to be met, grow the chips - --bit-TagsInput-tag-min-height: 1.5rem with a roomier --bit-TagsInput-tag-padding - and widen the buttons through Classes.DismissButton; the keyboard reaches both at any size, Delete removing the focused chip and Alt with the arrows moving it.

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 of a list of measurements. The prefix sits in front of the chips and the suffix after everything else, the clear button included. Both are announced with the field - the input references them, ahead of the Description - so a reader is told what a sighted user reads inside it. PrefixTemplate and SuffixTemplate take markup instead, for an icon or a badge; markup is as likely to be a glyph as a word, so those are not announced and what they mean has to be in the Label as well.

TagTemplate replaces the text of every chip with markup of your own, the tag being the context; the chip around it - its background, its focus ring, its dismiss button - is still the component's, so a template only describes what goes inside. Markup is not something a name can be read off, though, so a chip drawing Ada Lovelace over the tag [email protected] is announced by neither the one nor the other: GetTagName is what names it, and the name it gives is carried by the chip, by its dismiss button, by its reorder handle, by its inline edit and by every announcement the tag takes part in. GetTagClass and GetTagStyle are what tell one chip apart from the next: each receives a tag and returns what that particular chip should carry on top of the shared styling - the address that is not well formed drawn in red, each priority in a color of its own. They run for every drawn tag on every render, so they belong to a lookup rather than a computation, and an exception thrown out of one leaves that chip looking like all the others.

The value is the list of tags itself, bound two ways with @bind-Value; DefaultValue seeds an uncontrolled field read through OnChange instead. Removing the last tag leaves the value at null rather than at an empty list, which is what makes a plain [Required] catch an empty field. Inside an EditForm the field validates like any other input: it reports to the EditContext, paints the error state, marks its input with aria-invalid and turns its description red - the annotations that apply being the collection ones. Enter confirms a tag, so it is held back from submitting the form; CancelConfirmKeysOnEmpty hands it back once there is nothing left to confirm. Name posts the whole list as a single field of a plain HTML form, the tags joined by the first separator.

OnBeforeAdd and OnBeforeRemove run before the list changes and can call the change off with args.Cancel, which is the hook for a confirmation or a rule that lives on the server. OnBeforeAdd can also correct the tag on its way in by writing to args.Tag - the address an alias resolves to, the id a code stands for - and what it leaves there is what is added, announced and reported. OnAdd receives every tag added in one go (a paste adds several), OnRemove the one taken off, OnInvalid the one refused 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, so a list of your own is never left filtering on a word that is already a chip. OnTagClick turns a chip into a way in to whatever it stands for - the card of the recipient, the filter the tag is built on - without taking the focus the click already gives it, and Enter on the focused chip does the very same thing, so the way in is not one only a pointer has (unless EditableTags has claimed that key for the inline edit). OnFocusIn, OnFocusOut and OnKeyDown report the plain input events on top of them.

The component can be driven from the outside: AddTagAsync and AddTagsAsync add through exactly the same pipeline as typing does, RemoveTagAsync and RemoveTagAtAsync take one off, MoveTagAsync moves one - raising OnReorder, and without needing AllowReorder, which offers the gesture to the user rather than permitting the list to be reordered - EditTagAsync opens the inline edit of one, SetInputTextAsync writes the text of the input (which is what fills the field from a suggestion list of your own driven by OnInput), Clear empties the list and FocusAsync puts the caret back. All of them do nothing while the field is disabled or read-only, and all go through the callbacks, the announcements and the validation the equivalent gesture does.

BitParams carries a BitTagsInputParams down to every tags input under it, so a form, a panel or a whole page sets the shared look, the shared separators and the shared rules once instead of on every field. What it carries is a default and not an override: a field that writes a parameter for itself keeps its own value, and only what it left unset is filled in from the cascade. What travels down is the configuration and never the value - Value, DefaultValue, Name, Required and ReadOnly belong to the one field that holds them, as do the templates and the event callbacks.

Color picks the 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. The error state of a failing validation always wins over it, which keeps an invalid field recognizable whatever its color is.

The dismiss button of each tag and the clear button of the field take their icon either from the built-in Fluent UI set, through DismissIconName and ClearButtonIconName, or from any external 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 when both are given.

Size scales the field, the chips and the text inside them together. An empty field takes the control height of its size class, so it lines up with the text fields and pickers beside it in a form, and grows from there with every line of chips that wraps into it.

Style and Class reach the root element only, while Styles and Classes reach every part by name - the label, the description, the sentence a refusal is reported with, the counter, the input container, the affixes, the wrapper of the tags, each tag and its text, the reorder handle and the dismiss button with their icons, the fold chip, the input, the little edit input, the loading spinner and the clear button - plus the state slots Focused, FocusedTag, FixedTag, EditingTag (the chip being corrected), PickedUpTag (the chip waiting to be put down) and DuplicateTag (the chip a refused duplicate collided with). Prefer Classes when your CSS should own states such as hover, which inline styles cannot express.

The component also reads a set of CSS variables off its elements. They inherit, so a value on :root or any ancestor re-skins every tags input below it, and one on the Style of an instance re-skins that one and any tags input nested in it. They restyle the default, not a choice: an explicit Color or Size wins over the variables for what it sets.

CSS variables:

Set once on an ancestor, inherited by every field inside it:

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 keeps its logical order: the first chip is always the first tag of the list.