MUITagsInput
MUITagsInput renders a
TextField that turns typed or
pasted text into chips. Add, delete and paste actions can be intercepted,
transformed or blocked, and the visible chip count can be limited when
unfocused.
Working
MUITagsInput works as follows:
- Users can type a keyword, press Enter or the delimiter key (default
","), and see it rendered as a chip, with the input field cleared for the next entry. - Pasting comma-separated values automatically generates
chips for each value. The delimiter can also be configured, for example
"|". - Users can remove a chip by clicking its "x" button.
- Pressing the Backspace or Delete key when the input is empty removes the last chip.
- When the field is unfocused, only the first two chips are displayed
by default. This can be customized via the
limitTagsprop, with-1showing all chips.
Usage
import MUITagsInput, { MUITagsInputProps } from '@nish1896/mui-components/mui/tags-input';const [tags, setTags] = useState<string[]>([]);
<MUITagsInput
fieldName="tags"
value={tags}
onValueChange={({ newValue }) => setTags(newValue)}
delimiter="|"
/>onValueChange receives { newValue }: the next array of tags. To validate,
transform or block a tag before it is added, use onTagAdd.
value is always a string[], and a missing value is an empty list. Removing
the last tag emits [], never null. Tags are trimmed, empty entries are
dropped, and a tag is skipped when it matches an existing one, ignoring letter
case and spaces (React and react, or New York and newyork).
Delimiter
The delimiter (default ',') is the key that turns the typed text into a tag,
alongside Enter. Pasted text is split on it as well, so pasting
red;green;blue creates three tags when the delimiter is ';'. Leading and
trailing spaces around each tag are trimmed, so red; green ; blue creates the
same three tags.
<MUITagsInput
fieldName="colors"
value={colors}
onValueChange={({ newValue }) => setColors(newValue)}
delimiter=";"
/>The delimiter is matched against the pressed key, so use a single character. That key is intercepted, which means a tag can't contain the delimiter.
Tag Events
Use onTagAdd, onTagDelete, and onTagPaste to validate, transform, or
prevent tag changes before the form value is updated. Each callback receives a
single object argument with the current field value available as currentValue.
onTagAdd— called before a tag is added, withcurrentValue(the field value before the addition) andnewTag(the tag the user is attempting to add). Returnfalseto block the tag, a replacementstringto add a different value instead ofnewTag, ortrue/voidto addnewTagunchanged.onTagDelete— called before a tag is removed, withcurrentValue(the field value before the removal) anddeletedTag(the tag being removed). Returnfalseto prevent the deletion, ortrue/voidto allow it.onTagPaste— called when one or more tags are pasted, withcurrentValueandpastedTags(the tags parsed from the pasted text — already split on the configureddelimiter, trimmed, and deduplicated). Returnfalseto discard all pasted tags, astring[]to replace them with a custom set, orvoidto addpastedTagsunchanged.
<MUITagsInput
fieldName="tags"
value={tags}
onValueChange={({ newValue }) => setTags(newValue)}
onTagAdd={({ newTag, currentValue }) => {
if (newTag.length < 3 || currentValue.includes(newTag)) {
return false;
}
}}
onTagDelete={({ deletedTag }) => {
if (deletedTag.includes('sh')) {
return false;
}
}}
onTagPaste={({ pastedTags }) => (
pastedTags.filter(tag => tag.length >= 3)
)}
/>Limiting the visible tags
While the field is not focused, only the first limitTags tags (default 2)
are shown, followed by a "+N more" chip. Focusing the field shows every tag.
Set limitTags to -1 to always show all of them. getLimitTagsText receives
the number of hidden tags and returns the text of the extra chip:
<MUITagsInput
fieldName="skills"
value={skills}
onValueChange={({ newValue }) => setSkills(newValue)}
limitTags={3}
getLimitTagsText={hiddenTags => `${hiddenTags} more…`}
/>Maximum number of tags
maxTags caps how many tags the field holds. By default there is no limit. Once
it is reached:
- New tags typed from the keyboard are ignored, and the text stays in the input.
- Pasted tags are cut to the free slots. Pasting five tags with two slots left adds the first two.
onTagAdd isn't called for a tag that is blocked by the limit. onTagPaste
still receives every parsed tag, and its result is cut to the free slots
afterwards. A counter in helperText tells users how many slots are left:
<MUITagsInput
fieldName="skills"
value={skills}
onValueChange={({ newValue }) => setSkills(newValue)}
maxTags={5}
helperText={`${skills.length}/5 tags`}
/>Customizing the chips
ChipProps is forwarded to every tag
Chip — for example color, variant,
size or an icon. It also applies to the "+N more" chip. The id,
role, label, disabled and onDelete props are controlled by the
component:
<MUITagsInput
fieldName="topics"
value={topics}
onValueChange={({ newValue }) => setTopics(newValue)}
ChipProps={{ color: 'primary', variant: 'outlined', size: 'small' }}
/>Transform tag content
By default, each chip shows its tag exactly as it was typed. To transform how a
tag is displayed, for example by adding a # prefix, changing its letter case
or adding an icon, pass a function to renderTagLabel. The stored value stays
the same; only the chip's label changes.
renderTagLabel receives a tag string and returns the ReactNode to display as
that chip's label, instead of the plain text. For example, to prefix every tag
with #:
<MUITagsInput
fieldName="topics"
value={topics}
onValueChange={({ newValue }) => setTopics(newValue)}
renderTagLabel={tag => `#${tag}`}
/>The label can be any element, such as an icon next to the text:
import LocalOfferIcon from '@mui/icons-material/LocalOffer';
<MUITagsInput
fieldName="topics"
value={topics}
onValueChange={({ newValue }) => setTopics(newValue)}
renderTagLabel={tag => (
<>
<LocalOfferIcon
sx={{
fontSize: 14,
mr: 0.5,
verticalAlign: 'middle'
}}
/>
{tag}
</>
)}
/>This only transforms the content display in an individual chip. value, the
onTagAdd, onTagDelete and onTagPaste callbacks, and the duplicate check
all keep using the original tag, so #react is shown but 'react' is stored.
The "+N more" chip isn't affected; use getLimitTagsText to change it.
API
MUITagsInputProps also accepts the remaining
TextFieldProps, with some props
excluded, including value, multiline and error.
Props marked with * are required.
| Name | Type | Description |
|---|---|---|
fieldName* | string | Name/path of the field. Used to derive the id, the default label, and the name attribute. This prop is required for all components. |
value | string[] | null | Current tags of the field. undefined/null are treated as an empty tag list. |
onValueChange* | ({ newValue }) => void | Called with the next tag array after tags are added or removed. |
delimiter | string | Character used to separate tags when typing or pasting. Pressing this key commits the current input as one or more tags. Default: ',' |
onTagAdd | ({ currentValue, newTag }) => boolean | string | void | Called before a tag is added. Return false to block the tag, a replacement string to transform it, or nothing to allow it unchanged. |
onTagDelete | ({ currentValue, deletedTag }) => boolean | void | Called before a tag is removed. Return false to prevent deletion. |
onTagPaste | ({ currentValue, pastedTags }) => string[] | boolean | void | Called when tags are pasted. Return false to reject all, a string[] to replace the parsed tags, or nothing to use them unchanged. Tags are split by delimiter, trimmed, and deduplicated before this callback. |
limitTags | number | Maximum number of tags shown when the input is not focused. Set to -1 to always show all tags.Default: 2 |
getLimitTagsText | (more: number) => ReactNode | Custom label rendered for the hidden selections counter. Receives the number of hidden values. |
maxTags | number | Maximum number of tags that can be added. Keyboard entries beyond the limit are ignored; pasted tags are truncated to fit. |
renderTagLabel | (tag: string) => ReactNode | Custom renderer for each visible tag label. Receives the tag value and returns the content displayed inside the chip. |
ChipProps | ChipProps | ChipProps forwarded to chips rendered for selected values. |
label | ReactNode | Label displayed for the field. Defaults to a human-readable label derived from fieldName, e.g. firstName becomes "First Name". |
showLabelAboveFormField | boolean | When true, renders the field label above the form field in the FormLabel component, instead of inside or beside it. Takes precedence over allLabelsAboveFields from the ConfigProvider, so false keeps the label inside this field even when the config places every label above its field. |
hideLabel | boolean | When true, hides the rendered field label while preserving accessible labeling where possible. |
formLabelProps | FormLabelProps | FormLabelProps forwarded to the internal FormLabel. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component. |
required | boolean | Indicates that the field is mandatory by adding an asterisk symbol (*) to the form label and setting the relevant accessibility attributes. |
errorMessage | string | string[] | Validation error for the field — pass a single message string, or a string[] when the field can fail multiple rules at once (every message is shown together). A non-empty string or array puts the field in an error state; undefined/''/[] clear it.Normalize your form library's error shape to this at the call site (e.g. an RHF FieldError via its .message). Use renderError to customize how the message(s) are rendered. |
renderError | (errors: string[]) => ReactNode | Custom renderer for the resolved error message(s), called only when the field is in an error state. Always receives a string[] — use errors[0] for the common single-message case, or map over errors when a field fails several rules. By default a single message renders as text and multiple messages render on separate lines. |
hideErrorMessage | boolean | If true, hides the error message text while keeping the field in an error state. |
formHelperTextProps | FormHelperTextProps | FormHelperTextProps forwarded to the internal FormHelperText. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component. |
customIds | { field, label, helperText, error } | Overrides the default field, label, helper text, and error IDs used for accessibility. |
Playground
Integrated with Formik — covers onTagAdd /
onTagDelete / onTagPaste, delimiter, maxTags, limitTags +
getLimitTagsText, renderTagLabel and ChipProps.
Source Code
View the full implementation of this component on GitHub.