MUI Components
NPM

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 limitTags prop, with -1 showing 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, with currentValue (the field value before the addition) and newTag (the tag the user is attempting to add). Return false to block the tag, a replacement string to add a different value instead of newTag, or true/void to add newTag unchanged.
  • onTagDelete — called before a tag is removed, with currentValue (the field value before the removal) and deletedTag (the tag being removed). Return false to prevent the deletion, or true/void to allow it.
  • onTagPaste — called when one or more tags are pasted, with currentValue and pastedTags (the tags parsed from the pasted text — already split on the configured delimiter, trimmed, and deduplicated). Return false to discard all pasted tags, a string[] to replace them with a custom set, or void to add pastedTags unchanged.
<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.

NameTypeDescription
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.
valuestring[] | 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.
delimiterstring
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.
limitTagsnumber
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.
maxTagsnumber
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.
ChipPropsChipProps
ChipProps forwarded to chips rendered for selected values.
labelReactNode
Label displayed for the field. Defaults to a human-readable label derived from fieldName, e.g. firstName becomes "First Name".
showLabelAboveFormFieldboolean
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.
hideLabelboolean
When true, hides the rendered field label while preserving accessible labeling where possible.
formLabelPropsFormLabelProps
FormLabelProps forwarded to the internal FormLabel. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component.
requiredboolean
Indicates that the field is mandatory by adding an asterisk symbol (*) to the form label and setting the relevant accessibility attributes.
errorMessagestring | 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.
hideErrorMessageboolean
If true, hides the error message text while keeping the field in an error state.
formHelperTextPropsFormHelperTextProps
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.

Max 5 tags, lowercased & de-duplicated on add

Type a skill and press Enter or comma (max 5); maximum of 3 tags visible at once

Custom delimiter, custom chip render & a locked tag

#react
#mui
Paste is lowercased; '|' delimiter; the 'react' tag can't be removed

Form State - Values & Errors

Source Code

View the full implementation of this component on GitHub.