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="|"
/>

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)
  )}
/>

Props#

MUITagsInputProps also accepts the remaining TextFieldProps except value, defaultValue, multiline and rows. 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.
`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.
`delimiter`	`string`	Character used to separate tags when typing or pasting. Pressing this key commits the current input as one or more tags. Default: `','`
`maxTags`	`number`	Maximum number of tags that can be added. Keyboard entries beyond the limit are ignored; pasted tags are truncated to fit.
`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.
`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.
`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.

Number Input

File Uploader