## TagsInput Capture a list of values from user with free input and suggestions Category: Combobox ### Made with Combobox `TagsInput` is built on top of [Combobox](https://mantine.dev/core/combobox/) and covers common use cases. If you need more advanced behavior or want to extend its functionality, you can create your own custom `TagsInput` component. See this [GitHub repository](https://github.com/AnnMarieW/dmc_custom_components) for custom DMC component examples. ### Simple Example `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. By default, `enter key` and `,` will select the typed value. ```python import dash_mantine_components as dmc from dash import Output, Input, html, callback component = html.Div( [ dmc.TagsInput( label="Select frameworks", placeholder="Select all you like!", id="framework-tags-input", value=["ng", "vue"], w=400, mb=10, ), dmc.Text(id="tags-input-value"), ] ) @callback( Output("tags-input-value", "children"), Input("framework-tags-input", "value") ) def select_value(value): return ", ".join(value) ``` ### Data Format Note that the `data` format is different than components like `Select` and `Multi Select`. See [Why can I not use value/label data structure with TagsInput?](https://help.mantine.dev/q/autocomplete-value-label) `TagsInput` `data` prop accepts data in one of the following formats: ```python data = ["React", "Angular", "Svelte", "Vue"] # or data = [ {"group": "Frontend", "items": ["React", "Angular"]}, {"group": "Backend", "items": ["Express", "Django"]} ] ``` ### Clearable Set `clearable` prop to display the clear button in the right section. The button is not displayed when: * The component does not have a value * The component is disabled * The component is read only ```python import dash_mantine_components as dmc component = dmc.TagsInput( label="Press Enter to submit a tag", value=["React"], w=400, clearable=True, ) ``` ### Max selected values You can limit the number of selected values with `maxTags` prop. This will not allow adding more values once the limit is reached. ```python import dash_mantine_components as dmc component = dmc.TagsInput( label="Select frameworks", description="You can select a maximum of 3 frameworks.", maxTags=3, w=400, ) ``` ### Accept value on blur 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. ```python import dash_mantine_components as dmc from dash import Output, Input, html, callback component = html.Div( [ dmc.TagsInput( label="Value is accepted on blur", placeholder="Select all you like!", id="framework-tags-input1", value=["Pandas", "NumPy"], w=400, mb=10, ), dmc.Text(id="tags-input-value1", mb="xl"), dmc.TagsInput( label="Value IS NOT accepted on blur", placeholder="Select all you like!", id="framework-tags-input2", value=["Pandas", "NumPy"], acceptValueOnBlur=False, w=400, mb=10, ), dmc.Text(id="tags-input-value2"), ] ) @callback( Output("tags-input-value1", "children"), Input("framework-tags-input1", "value") ) def select_value(value): return f"You selected {value}" @callback( Output("tags-input-value2", "children"), Input("framework-tags-input2", "value") ) def select_value(value): return f"You selected {value}" ``` ### Allow duplicates By default, `TagsInput` does not allow adding duplicate values, but you can change this behavior by setting `allowDuplicates` prop. Value is considered duplicate if it is already present in the `value` array, regardless of the case and trailing whitespace. ```python import dash_mantine_components as dmc component = dmc.TagsInput( label="Press Enter to submit a tag", placeholder="Duplicates are allowed", allowDuplicates=True, w=400, ) ``` ### Split chars By default, `TagsInput` splits values by comma (`,`), but 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`: ```python import dash_mantine_components as dmc component = dmc.TagsInput( label="Press Enter to submit a tag", placeholder="Enter tag", splitChars=[",", " ", "|"], w=400, ) ``` ### With suggestions `TagsInput` can be used with suggestions, it will render suggestions list under input and allow selecting 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](/components/multiselect) component instead. ```python import dash_mantine_components as dmc component = dmc.TagsInput( w=400, label="Press Enter to submit a tag", placeholder="Pick tag from list", data=["React", "Angular", "Svelte"], ) ``` ### Grouping ```python import dash_mantine_components as dmc component = dmc.TagsInput( data=[ { "group": "Data Analysis", "items": [ {"value": "Pandas", "label": "Pandas"}, {"value": "NumPy", "label": "NumPy"}, ], }, { "group": "Deep Learning", "items": [ {"value": "TensorFlow", "label": "TensorFlow"}, {"value": "PyTorch", "label": "PyTorch"}, ], }, ], w=400, ) ``` ### Large data sets The best strategy for large data sets is to limit the number of options that are rendered at the same time. You can do it with `limit` prop. Example of `TagsInput` with 100 000 options, 5 options are rendered at the same time: ```python import dash_mantine_components as dmc component = dmc.TagsInput( label="100,000 options", data=[f"Option {i}" for i in range(100000)], placeholder="use limit to optimize performance", limit=5, w=400, ) ``` ### renderOption `renderOption` function allows you to customize option rendering. Note: This example uses custom JavaScript defined in the assets folder. Learn more in the "Functions As Props" section of this document. ```python import dash_mantine_components as dmc groceries = { "Apples": { "emoji": "🍎", "description": "Crisp and juicy snacking delight", }, "Bread": { "emoji": "🍞", "description": "Freshly baked daily essential", }, "Bananas": { "emoji": "🍌", "description": "Perfect for a healthy breakfast", }, "Eggs": { "emoji": "🥚", "description": "Versatile protein source for cooking", }, "Broccoli": { "emoji": "🥦", "description": "Nutrient-rich green vegetable", }, } component = dmc.TagsInput( label="Groceries", placeholder="Pick tag from list or type to add new", data=list(groceries.keys()), maxDropdownHeight=300, renderOption={ "function": "renderGroceryOption", "options": {"data": groceries}, }, ) ``` ```javascript var dmcfuncs = window.dashMantineFunctions = window.dashMantineFunctions || {}; var dmc = window.dash_mantine_components; dmcfuncs.renderGroceryOption = function ({ option }, { data }) { const item = data[option.value]; return React.createElement( dmc.Group, null, React.createElement( dmc.Text, { span: true, fz: 24 }, item.emoji ), React.createElement( "div", null, React.createElement(dmc.Text, { key: "label"}, option.value, ), React.createElement( dmc.Text, { size: "xs", opacity: 0.5, key: "description" }, item.description ) ) ); }; ``` ### Options filtering By default, `TagsInput` filters options by checking if the option label contains input value. You can change this behavior with `filter`. The filter function receives an object with the following properties as a single argument: - `options` – array of options or options groups, all options are in `{ value: string; label: string; disabled?: boolean }` format - `search` – current search query - `limit` – value of limit prop passed to `Select` Note: This example uses custom JavaScript defined in the assets folder. Learn more in the "Functions As Props" section of this document. Example of a custom filter function that matches options by words instead of letters sequence: ```python import dash_mantine_components as dmc component = dmc.TagsInput( label="What countries have you visited?", placeholder="Pick value or enter anything", data=[ "Great Britain", "Canada", "United States", ], filter={"function": "filterCountries"}, ) ``` ```javascript var dmcfuncs = window.dashMantineFunctions = window.dashMantineFunctions || {}; dmcfuncs.filterCountries = function ({ options, search }) { const queryWords = search.toLowerCase().trim().split(" "); return options.filter((option) => { const words = option.label.toLowerCase().trim().split(" "); return queryWords.every((word) => words.some((labelWord) => labelWord.includes(word)) ); }); }; ``` ### Sort options By default, options are sorted by their position in the data array. You can change this behavior with `filter` function: Note: This example uses custom JavaScript defined in the assets folder. Learn more in the "Functions As Props" section of this document. ```python import dash_mantine_components as dmc component = dmc.TagsInput( label="Your favorite Python library", placeholder="Pick value or enter anything", data=[ "4 – NumPy", "1 – Pandas", "3 – Scikit-learn", "2 – Plotly", ], filter={"function": "filterPythonLibs"}, ) ``` ```javascript var dmcfuncs = window.dashMantineFunctions = window.dashMantineFunctions || {}; dmcfuncs.filterPythonLibs = function ({ options, search }) { const query = search.toLowerCase().trim(); const result = options.filter((option) => option.label.toLowerCase().trim().includes(query) ); result.sort((a, b) => a.label.localeCompare(b.label)); return result; }; ``` ### Scrollable dropdown 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`. ```python import dash_mantine_components as dmc component = dmc.Paper( [ dmc.TagsInput( label="Scrollable dropdown", data=[f"Option {i}" for i in range(100)], placeholder="Pick value", maxDropdownHeight=300, w=400, ), dmc.TagsInput( label="With native scroll", data=[f"Option {i}" for i in range(100)], placeholder="Pick value", withScrollArea=False, styles={"dropdown": {"maxHeight": 200, "overflowY": "auto"}}, w=400, mt="md", ), ] ) ``` ### Disabled options When an 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 a callback to filter them out. ```python import dash_mantine_components as dmc component = dmc.TagsInput( label="Enter tags", placeholder="Some tags are disabled", data = [ {"value": "Pandas"}, {"value": "NumPy"}, {"value": "TensorFlow", "disabled": True}, {"value": "PyTorch", "disabled": True}, ], w=400, ) ``` ### Combobox props You can override `Combobox` props with `comboboxProps`. It is useful when you need to change some of the props that are not exposed by `TagsInput`, for example `withinPortal`: ```python dmc.TagsInput(comboboxProps={"withinPortal": False}) ``` ### Change dropdown z-index ```python dmc.TagsInput(comboboxProps={"zIndex": 1000}) ``` ### Inside Popover To use `TagsInput` inside popover, you need to set `withinPortal=False`: ```python import dash_mantine_components as dmc component = dmc.Popover( width=300, position="bottom", withArrow=True, shadow="md", children=[ dmc.PopoverTarget(dmc.Button("Toggle Popover")), dmc.PopoverDropdown( dmc.TagsInput( label="Your favorite library", placeholder="Pick value", data=["Pandas", "NumPy", "TensorFlow", "PyTorch"], comboboxProps={"withinPortal": False}, ) ), ], ) ``` ### Dropdown open in a callback ```python import dash_mantine_components as dmc from dash import Output, Input, html, callback component = html.Div( [ dmc.Button("Toggle dropdown", id="btn-tags-opened", n_clicks=0), dmc.TagsInput( label="Select your favorite library", placeholder="Select value", id="tags-opened", value=["pd"], data=[ {"value": "pd", "label": "Pandas"}, {"value": "np", "label": "NumPy"}, {"value": "tf", "label": "TensorFlow"}, {"value": "torch", "label": "PyTorch"}, ], w=400, mb=10, ), ] ) @callback( Output("tags-opened", "dropdownOpened"), Input("btn-tags-opened", "n_clicks") ) def select_value(n): if n % 2 == 0: return False return True ``` ### Dropdown position 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: ```python import dash_mantine_components as dmc component = dmc.TagsInput( label="Your favorite library", placeholder="Pick value", data=["Pandas", "NumPy", "TensorFlow", "PyTorch"], comboboxProps={"position": "top", "middlewares": {"flip": False, "shift": False}}, ) ``` ### Dropdown width To change dropdown width, set `width` prop in `comboboxProps`. By default, dropdown width is equal to the input width. ```python import dash_mantine_components as dmc component = dmc.TagsInput( label="Your favorite library", placeholder="Pick value", data=["Pandas", "NumPy", "TensorFlow", "PyTorch"], comboboxProps={"position": "bottom-start", "width": 200}, ) ``` ### Dropdown offset To change dropdown offset, set `offset` prop in `comboboxProps`: ```python import dash_mantine_components as dmc component = dmc.TagsInput( label="Your favorite library", placeholder="Pick value", data=["Pandas", "NumPy", "TensorFlow", "PyTorch"], comboboxProps={ "position": "bottom", "middlewares": {"flip": False, "shift": False}, "offset": 0, }, ) ``` ### Dropdown animation By default, dropdown animations are disabled. To enable them, you can set `transitionProps`, which will be passed down to the underlying `Transition` component. ```python import dash_mantine_components as dmc component = dmc.TagsInput( label="Your favorite library", placeholder="Pick values", data=["Pandas", "NumPy", "TensorFlow", "PyTorch"], comboboxProps={"transitionProps": {"transition": "pop", "duration": 200}}, ) ``` ### Dropdown padding ```python import dash_mantine_components as dmc component = dmc.Paper( [ dmc.TagsInput( label="Zero padding", data=["Pandas", "NumPy", "TensorFlow", "PyTorch"], placeholder="Pick value", comboboxProps={"dropdownPadding": 0}, w=400, ), dmc.TagsInput( label="10px padding", data=["Pandas", "NumPy", "TensorFlow", "PyTorch"], placeholder="Pick value", comboboxProps={"dropdownPadding": 10}, w=400, mt="md", ), ] ) ``` ### Dropdown shadow ```python import dash_mantine_components as dmc component = dmc.TagsInput( label="Your favorite library", placeholder="Pick value", data=["Pandas", "NumPy", "TensorFlow", "PyTorch"], comboboxProps={"shadow": "md"}, ) ``` ### Left and right sections `MultiSelect` supports `leftSection` and `rightSection` props. These sections are rendered with absolute position 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: - `rightSection`/`leftSection` – component to render on the corresponding side of input - `rightSectionWidth`/`leftSectionWidth` – controls width of the right section and padding on the corresponding side of the input. By default, it is controlled by component size prop. - `rightSectionPointerEvents`/`leftSectionPointerEvents` – controls pointer-events property of the section. If you want to render a non-interactive element, set it to none to pass clicks through to the input. ```python import dash_mantine_components as dmc from dash_iconify import DashIconify component = dmc.Paper( [ dmc.TagsInput( label="Your favorite library", data=["Pandas", "NumPy", "TensorFlow", "PyTorch"], placeholder="Pick values", leftSectionPointerEvents="none", leftSection=DashIconify(icon="bi-book"), w=400, ), dmc.TagsInput( label="Your favorite library", data=["Pandas", "NumPy", "TensorFlow", "PyTorch"], placeholder="Pick values", rightSectionPointerEvents="none", rightSection=DashIconify(icon="bi-book"), w=400, mt="md", ), ] ) ``` ### Input Props `TagsInput` component supports `Input` and Input Wrapper components features and all input element props. `TagsInput` documentation does not include all features supported by the component – see Input documentation to learn about all available features. ### Read only Set `readOnly` to make the input read only. When `readOnly` is set, `TagsInput` will not show suggestions and value cannot be updated by the user entering data in the input. ```python import dash_mantine_components as dmc component = dmc.TagsInput( label="Read only", placeholder="Enter tag", readOnly=True, value=["First", "Second"], w=400, ) ``` ### Disabled Set `disabled` to disable the input. When `disabled` is set, user cannot interact with the input and `TagsInput` will not show suggestions. ```python import dash_mantine_components as dmc component = dmc.TagsInput( label="Disabled", disabled=True, value=["First", "Second"], w=400, ) ``` ### Styles API This component supports Styles API. With Styles API, you can customize styles of any inner element. See the Styling and Theming sections of these docs for more information. Refer to the Mantine TagsInput Style API [interactive demo](https://mantine.dev/core/tags-input/#styles-api) for help in identifying each selector. | Name | Static selector | Description | |:------------|:-------------------------------|:-------------------------------------------------| | wrapper | .mantine-TagsInput-wrapper | Root element of the Input | | input | .mantine-TagsInput-input | Input element | | section | .mantine-TagsInput-section | Left and right sections | | root | .mantine-TagsInput-root | Root element | | label | .mantine-TagsInput-label | Label element | | required | .mantine-TagsInput-required | Required asterisk element, rendered inside label | | description | .mantine-TagsInput-description | Description element | | error | .mantine-TagsInput-error | Error element | | dropdown | .mantine-TagsInput-dropdown | Dropdown root element | | options | .mantine-TagsInput-options | Options wrapper | | option | .mantine-TagsInput-option | Option | | empty | .mantine-TagsInput-empty | Nothing found message | | group | .mantine-TagsInput-group | Options group wrapper | | groupLabel | .mantine-TagsInput-groupLabel | Options group label | | pill | .mantine-TagsInput-pill | Value pill | | inputField | .mantine-TagsInput-inputField | Input field | | pillsList | .mantine-TagsInput-pillsList | List of pills, also contains input field | ### Keyword Arguments #### TagsInput - id (string; optional): Unique ID to identify this component in Dash callbacks. - acceptValueOnBlur (boolean; optional): Determines whether the value typed in by the user but not submitted should be accepted when the input is blurred, True by default. - allowDuplicates (boolean; optional): Determines whether duplicate tags are allowed, `False` by default. - aria-* (string; optional): Wild card aria attributes. - attributes (boolean | number | string | dict | list; optional): Passes attributes to inner elements of a component. See Styles API docs. - className (string; optional): Class added to the root element, if applicable. - classNames (dict; optional): Adds custom CSS class names to inner elements of a component. See Styles API docs. - clearButtonProps (dict; optional): Props passed down to the clear button. `clearButtonProps` is a dict with keys: - clearable (boolean; optional): Determines whether the clear button should be displayed in the right section when the component has value, `False` by default. - comboboxProps (dict; optional): Props passed down to `Combobox` component. `comboboxProps` is a dict with keys: - darkHidden (boolean; optional): Determines whether component should be hidden in dark color scheme with `display: none`. - data (list of strings; optional): Data displayed in the dropdown. - data-* (string; optional): Wild card data attributes. - description (a list of or a singular dash component, string or number; optional): Contents of `Input.Description` component. If not set, description is not rendered. - descriptionProps (dict with strings as keys and values of type boolean | number | string | dict | list; optional): Props passed down to the `Input.Description` component. - disabled (boolean; optional): Sets `disabled` attribute on the `input` element. - dropdownOpened (boolean; optional): Controlled dropdown opened state. - error (a list of or a singular dash component, string or number; optional): Contents of `Input.Error` component. If not set, error is not rendered. - errorProps (dict with strings as keys and values of type boolean | number | string | dict | list; optional): Props passed down to the `Input.Error` component. - filter (boolean | number | string | dict | list; optional): A Function based on which items are filtered and sorted. See https://www.dash-mantine-components.com/functions-as-props. - hiddenFrom (string; optional): Breakpoint above which the component is hidden with `display: none`. - hiddenInputProps (dict; optional): Props passed down to the hidden input. - hiddenInputValuesDivider (string; optional): Divider used to separate values in the hidden input `value` attribute, `','` by default. - inputProps (dict with strings as keys and values of type boolean | number | string | dict | list; optional): Props passed down to the `Input` component. - inputWrapperOrder (list of a value equal to: 'label', 'description', 'error', 'input's; optional): Controls order of the elements, `['label', 'description', 'input', 'error']` by default. - label (a list of or a singular dash component, string or number; optional): Contents of `Input.Label` component. If not set, label is not rendered. - labelProps (dict with strings as keys and values of type boolean | number | string | dict | list; optional): Props passed down to the `Input.Label` component. - leftSection (a list of or a singular dash component, string or number; optional): Content section rendered on the left side of the input. - leftSectionPointerEvents (a value equal to: 'auto', '-moz-initial', 'inherit', 'initial', 'revert', 'revert-layer', 'unset', 'none', 'all', 'fill', 'painted', 'stroke', 'visible', 'visibleFill', 'visiblePainted', 'visibleStroke'; optional): Sets `pointer-events` styles on the `leftSection` element, `'none'` by default. - leftSectionProps (dict; optional): Props passed down to the `leftSection` element. - leftSectionWidth (string | number; optional): Left section width, used to set `width` of the section and input `padding-left`, by default equals to the input height. - lightHidden (boolean; optional): Determines whether component should be hidden in light color scheme with `display: none`. - limit (number; optional): Maximum number of options displayed at a time, `Infinity` by default. - loading_state (dict; optional): Object that holds the loading state object coming from dash-renderer. For use with dash<3. `loading_state` is a dict with keys: - maxDropdownHeight (string | number; optional): `max-height` of the dropdown, only applicable when `withScrollArea` prop is `True`, `250` by default. - maxTags (number; optional): Maximum number of tags, `Infinity` by default. - mod (string | dict | list of string | dicts; optional): Element modifiers transformed into `data-` attributes. For example: "xl" or {"data-size": "xl"}. Can also be a list of strings or dicts for multiple modifiers. Falsy values are removed. - name (string; optional): Name prop. - openOnFocus (boolean; optional): If set, the dropdown opens when the input receives focus default `True`. - persisted_props (list of strings; optional): Properties whose user interactions will persist after refreshing the component or the page. Since only `value` is allowed this prop can normally be ignored. - persistence (string | number | boolean; optional): Used to allow user interactions in this component to be persisted when the component - or the page - is refreshed. If `persisted` is truthy and hasn't changed from its previous value, a `value` that the user has changed while using the app will keep that change, as long as the new `value` also matches what was given originally. Used in conjunction with `persistence_type`. Note: The component must have an `id` for persistence to work. - persistence_type (a value equal to: 'local', 'session', 'memory'; optional): Where persisted user changes will be stored: memory: only kept in memory, reset on page refresh. local: window.localStorage, data is kept after the browser quit. session: window.sessionStorage, data is cleared once the browser quit. - placeholder (string; optional): Placeholder. - pointer (boolean; optional): Determines whether the input should have `cursor: pointer` style, `False` by default. - radius (number; optional): Key of `theme.radius` or any valid CSS value to set `border-radius`, numbers are converted to rem, `theme.defaultRadius` by default. - readOnly (boolean; optional): Readonly. - renderOption (boolean | number | string | dict | list; optional): A function to render content of the option, replaces the default content of the option. See https://www.dash-mantine-components.com/functions-as-props. - required (boolean; optional): Adds required attribute to the input and a red asterisk on the right side of label, `False` by default. - rightSection (a list of or a singular dash component, string or number; optional): Content section rendered on the right side of the input. - rightSectionPointerEvents (a value equal to: 'auto', '-moz-initial', 'inherit', 'initial', 'revert', 'revert-layer', 'unset', 'none', 'all', 'fill', 'painted', 'stroke', 'visible', 'visibleFill', 'visiblePainted', 'visibleStroke'; optional): Sets `pointer-events` styles on the `rightSection` element, `'none'` by default. - rightSectionProps (dict; optional): Props passed down to the `rightSection` element. - rightSectionWidth (string | number; optional): Right section width, used to set `width` of the section and input `padding-right`, by default equals to the input height. - scrollAreaProps (dict; optional): Props passed down to the underlying `ScrollArea` component in the dropdown. `scrollAreaProps` is a dict with keys: - searchValue (string; optional): Controlled search value. - selectFirstOptionOnChange (boolean; optional): Determines whether the first option should be selected when value changes, `False` by default. - selectFirstOptionOnDropdownOpen (boolean; optional): If set, the first option is selected when dropdown opens, `False` by default. - size (optional): Controls input `height` and horizontal `padding`, `'sm'` by default. - splitChars (list of strings; optional): Characters that should trigger tags split, `[',']` by default. - styles (boolean | number | string | dict | list; optional): Adds inline styles directly to inner elements of a component. See Styles API docs. - tabIndex (number; optional): tab-index. - value (list of strings; optional): Controlled component value. - variant (string; optional): variant. - visibleFrom (string; optional): Breakpoint below which the component is hidden with `display: none`. - withAsterisk (boolean; optional): Determines whether the required asterisk should be displayed. Overrides `required` prop. Does not add required attribute to the input. `False` by default. - withErrorStyles (boolean; optional): Determines whether the input should have red border and red text color when the `error` prop is set, `True` by default. - withScrollArea (boolean; optional): Determines whether the options should be wrapped with `ScrollArea.AutoSize`, `True` by default. - wrapperProps (dict with strings as keys and values of type boolean | number | string | dict | list; optional): Props passed down to the root element.