Capture a list of values from user with free input and suggestions
TagsInput is an opinionated component built on top of the Combobox component. It has a limited set of features to cover only basic use cases. If you need more advanced features, you can build your own component with Combobox . You can find examples of custom tags input components on the examples page .
TagsInput provides a way to enter multiple values. It can be used with suggestions or without them. TagsInput is similar to MultiSelect , but it allows entering custom values.
Set loading prop to display a loading indicator. By default, the loader is displayed on the right side of the input. You can change the position with the loadingPosition prop to 'left' or 'right' . This is useful for async operations like API calls, searches, or validations:
The TagsInput value must be an array of strings; other types are not supported. The onChange function is called with an array of strings as a single argument.
You can control the search value with searchValue and onSearchChange props:
Set the clearable prop to display the clear button in the right section. The button is not displayed when:
The clearSectionMode prop determines how the clear button and rightSection are rendered:
You can limit the number of selected values with the maxTags prop. This will not allow adding more values once the limit is reached.
By default, if the user types a value and blurs the input, the value is added to the list. You can change this behavior by setting acceptValueOnBlur to false . In this case, the value is added only when the user presses Enter or clicks on a suggestion.
By default, TagsInput does not allow adding duplicate values, but you can change this behavior by setting the allowDuplicates prop. A value is considered duplicate if it is already present in the value array, regardless of the case and trailing whitespace.
You can use the isDuplicate prop to control how duplicates are detected. It is a function that receives two arguments: tag value and current tags. The function must return true if the value is a duplicate.
Example of using isDuplicate to allow using the same value with different casing:
By default, TagsInput splits values by comma ( , ), you can change this behavior by setting splitChars prop to an array of strings. All values from splitChars cannot be included in the final value. Values are also split on paste.
Example of splitting by , , | and space:
TagsInput can be used with suggestions, it will render suggestions list under input and allow to select suggestions with keyboard or mouse. Note that user is not limited to suggestions, it is still possible to enter custom values. If you want to allow values only from suggestions, use MultiSelect component instead.
TagsInput data prop accepts data in one of the following formats:
Array of groups with string options:
Example of a custom filter function that matches options by words instead of letter sequence:
By default, options are sorted by their position in the data array. You can change this behavior with filter function:
You can implement fuzzy search using the fuse.js library to match options even with typos or partial matches:
The best strategy for large data sets is to limit the number of options that are rendered at the same time. You can do this with the limit prop. Note that if you use a custom filter function, you need to implement your own logic to limit the number of options in filter .
Example of TagsInput with 100,000 options, 5 options are rendered at the same time:
renderOption callback allows you to customize option rendering. It is called with option object. The function must return a React node.
renderPill callback allows customizing how pills are rendered. It is called with an object containing option (combobox item), value (string), onRemove (function) and disabled . Note that since TagsInput allows adding custom values, option property might be generated on the fly.
Tags are rendered with a star prefix
Set the withPillsReorder prop to allow reordering pills. Dropping a pill before or after another pill updates the component value accordingly. Reordering is automatically disabled when disabled or readOnly is set.
You can reorder pills with a mouse (drag-and-drop) or keyboard:
Focus follows the moved pill so multiple moves can be chained without re-focusing.
Tags can be reordered by dragging pills
If you use a custom pill renderer with the renderPill prop, spread the reorderProps from the render callback payload onto the focusable pill root element to keep reordering working. reorderProps carries the tabIndex , data-mantine-pill-index attribute and the keyboard handler that drive keyboard reorder, so it must land on the element the user can focus:
By default, the options list is wrapped with ScrollArea.Autosize . You can control dropdown max-height with maxDropdownHeight prop if you do not change the default settings.
If you want to use native scrollbars, set withScrollArea={false} . Note that in this case, you will need to change dropdown styles with Styles API .
Set floatingHeight="viewport" to make the dropdown grow to fill the available vertical space in the viewport. The flip middleware is disabled in this mode – the dropdown always opens in the configured direction and is constrained to the viewport edges instead of flipping to the other side. Useful when working with large option lists:
When option is disabled, it cannot be selected and is ignored in keyboard navigation. Note that user can still enter disabled option as a value. If you want to prohibit certain values, use controlled component and filter them out in onChange function.
You can override Combobox props with comboboxProps . This is useful when you need to change some of the props that are not exposed by TagsInput , for example withinPortal :
To use TagsInput inside popover, you need to set withinPortal: false :
You can control dropdown opened state with dropdownOpened prop. Additionally, you can use onDropdownClose and onDropdownOpen to listen to dropdown opened state changes.
By default, the dropdown is displayed below the input if there is enough space; otherwise it is displayed above the input. You can change this behavior by setting position and middlewares props, which are passed down to the underlying Popover component.
Example of dropdown that is always displayed above the input:
By default, dropdown animations are disabled. To enable them, you can set transitionProps , which will be passed down to the underlying Transition component.
To change dropdown width, set width prop in comboboxProps . By default, dropdown width is equal to the input width.
TagsInput supports leftSection and rightSection props. These sections are rendered with absolute positioning inside the input wrapper. You can use them to display icons, input controls, or any other elements.
You can use the following props to control sections styles and content:
TagsInput component supports Input and Input.Wrapper component features and all input element props. The TagsInput documentation does not include all features supported by the component – see the Input documentation to learn about all available features.
Set readOnly to make the input read only. When readOnly is set, TagsInput will not show suggestions and will not call onChange function.
Set disabled to disable the input. When disabled is set, user cannot interact with the input and TagsInput will not show suggestions.
TagsInput supports the Styles API ; you can add styles to any inner element of the component with the classNames prop. Follow the Styles API documentation to learn more.
Component Styles API
Hover over selectors to highlight corresponding elements
If TagsInput is used without the label prop, it will not be announced properly by screen readers:
Set aria-label to make the input accessible. In this case the label will not be visible, but screen readers will announce it:
If the label prop is set, the input will be accessible and it is not required to set aria-label :
To set aria-label on the clear button, use clearButtonProps . Note that it is required only when clearable is set.