Welcome to Mantine, React components library that you always wished for
Welcome to Mantine, React components library that you always wished for

TagsInput

Capture a list of values from user with free input and suggestions

Import

Source

View source code

Docs

Edit this page

Package

@mantine/core

Made with Combobox

TagsInput is an opinionated component built on top of Combobox component. It has a limited set of features to cover only the 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.

Usage

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.

import { TagsInput } from '@mantine/core';

function Demo() {
  return <TagsInput label="Press Enter to submit a tag" placeholder="Enter tag" />;
}

Controlled

TagsInput value must be an array of strings, other types are not supported. onChange function is called with an array of strings as a single argument.

import { useState } from 'react';
import { TagsInput } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState<string[]>([]);
  return <TagsInput data={[]} value={value} onChange={setValue} />;
}

Controlled search value

You can control search value with searchValue and onSearchChange props:

import { useState } from 'react';
import { TagsInput } from '@mantine/core';

function Demo() {
  const [searchValue, setSearchValue] = useState('');
  return (
    <TagsInput
      searchValue={searchValue}
      onSearchChange={setSearchValue}
      data={[]}
    />
  );
}

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
React
import { TagsInput } from '@mantine/core';

function Demo() {
  return (
    <TagsInput
      label="Press Enter to submit a tag"
      placeholder="Enter tag"
      defaultValue={['React']}
      clearable
    />
  );
}

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.

Add up to 3 tags

firstsecond
import { TagsInput } from '@mantine/core';

function Demo() {
  return (
    <TagsInput
      label="Press Enter to submit a tag"
      description="Add up to 3 tags"
      placeholder="Enter tag"
      maxTags={3}
      defaultValue={['first', 'second']}
    />
  );
}

Allow duplicates

By default TagsInput does not allow to add 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.

import { TagsInput } from '@mantine/core';

function Demo() {
  return (
    <TagsInput
      label="Press Enter to submit a tag"
      placeholder="Duplicates are allowed"
      allowDuplicates
    />
  );
}

Split chars

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 splitted on paste.

Example of splitting by ,, | and space:

import { TagsInput } from '@mantine/core';

function Demo() {
  return (
    <TagsInput
      label="Press Enter to submit a tag"
      placeholder="Enter tag"
      splitChars={[',', ' ', '|']}
    />
  );
}

With suggestions

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.

import { TagsInput } from '@mantine/core';

function Demo() {
  return (
    <TagsInput
      label="Press Enter to submit a tag"
      placeholder="Pick tag from list"
      data={['React', 'Angular', 'Svelte']}
    />
  );
}

Data formats

TagsInput data prop accepts data in one of the following formats:

Array of strings:

import { TagsInput } from '@mantine/core';

function Demo() {
  return <TagsInput data={['React', 'Angular']} />;
}

Array of groups with string options:

import { TagsInput } from '@mantine/core';

function Demo() {
  return (
    <TagsInput
      data={[
        { group: 'Frontend', items: ['React', 'Angular'] },
        { group: 'Backend', items: ['Express', 'Django'] },
      ]}
    />
  );
}

Options filtering

By default, TagsInput filters options by checking if the option label contains input value. You can change this behavior with filter prop.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 TagsInput

Example of a custom filter function that matches options by words instead of letters sequence:

import { TagsInput, ComboboxItem, OptionsFilter } from '@mantine/core';

const optionsFilter: OptionsFilter = ({ options, search }) => {
  const splittedSearch = search.toLowerCase().trim().split(' ');
  return (options as ComboboxItem[]).filter((option) => {
    const words = option.label.toLowerCase().trim().split(' ');
    return splittedSearch.every((searchWord) => words.some((word) => word.includes(searchWord)));
  });
};

function Demo() {
  return (
    <TagsInput
      label="What countries have you visited?"
      placeholder="Pick value or enter anything"
      data={['Great Britain', 'Russian Federation', 'United States']}
      filter={optionsFilter}
    />
  );
}

Sort options

By default, options are sorted by their position in the data array. You can change this behavior with filter function:

import { TagsInput, ComboboxItem, OptionsFilter } from '@mantine/core';

const optionsFilter: OptionsFilter = ({ options, search }) => {
  const filtered = (options as ComboboxItem[]).filter((option) =>
    option.label.toLowerCase().trim().includes(search.toLowerCase().trim())
  );

  filtered.sort((a, b) => a.label.localeCompare(b.label));
  return filtered;
};

function Demo() {
  return (
    <TagsInput
      label="Your favorite libraries"
      placeholder="Pick value or enter anything"
      data={['4 – React', '1 – Angular', '3 – Vue', '2 – Svelte']}
      filter={optionsFilter}
    />
  );
}

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. 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:

import { TagsInput } from '@mantine/core';

const largeData = Array(100_000)
  .fill(0)
  .map((_, index) => `Option ${index}`);

function Demo() {
  return (
    <TagsInput
      label="100 000 options tags input"
      placeholder="Use limit to optimize performance"
      limit={5}
      data={largeData}
    />
  );
}

renderOption

renderOption callback allows you to customize option rendering. It is called with option object. The function must return a React node.

import { Group, TagsInput, TagsInputProps, Text } from '@mantine/core';

const data: Record<string, { emoji: string; description: string }> = {
  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',
  },
};

const renderTagsInputOption: TagsInputProps['renderOption'] = ({ option }) => (
  <Group>
    <Text span fz={24}>
      {data[option.value].emoji}
    </Text>
    <div>
      <Text>{option.value}</Text>
      <Text size="xs" opacity={0.5}>
        {data[option.value].description}
      </Text>
    </div>
  </Group>
);

function Demo() {
  return (
    <TagsInput
      data={['Apples', 'Bread', 'Bananas', 'Eggs', 'Broccoli']}
      renderOption={renderTagsInputOption}
      label="Groceries"
      placeholder="Pick tag from list or type to add new"
      maxDropdownHeight={300}
    />
  );
}

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.

import { TagsInput } from '@mantine/core';

const data = Array(100)
  .fill(0)
  .map((_, index) => `Option ${index}`);

function Demo() {
  return (
    <>
      <TagsInput
        label="With scroll area (default)"
        placeholder="Pick value or enter anything"
        data={data}
        maxDropdownHeight={200}
      />

      <TagsInput
        label="With native scroll"
        placeholder="Pick value or enter anything"
        data={data}
        withScrollArea={false}
        styles={{ dropdown: { maxHeight: 200, overflowY: 'auto' } }}
        mt="md"
      />
    </>
  );
}

Group options

import { TagsInput } from '@mantine/core';

function Demo() {
  return (
    <TagsInput
      label="Enter tags"
      placeholder="Enter tags"
      data={[
        { group: 'Frontend', items: ['React', 'Angular'] },
        { group: 'Backend', items: ['Express', 'Django'] },
      ]}
    />
  );
}

Disabled options

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.

import { TagsInput } from '@mantine/core';

function Demo() {
  return (
    <TagsInput
      label="Enter tags"
      placeholder="Some tags are disabled"
      data={[
        { value: 'React' },
        { value: 'Angular' },
        { value: 'Vue', disabled: true },
        { value: 'Svelte', disabled: true },
      ]}
    />
  );
}

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:

import { TagsInput } from '@mantine/core';

function Demo() {
  return <TagsInput comboboxProps={{ withinPortal: false }} data={[]} />;
}

Change dropdown z-index

import { TagsInput } from '@mantine/core';

function Demo() {
  return <TagsInput comboboxProps={{ zIndex: 1000 }} data={[]} />;
}

Inside Popover

To use TagsInput inside popover, you need to set withinPortal: false:

import { Popover, Button, TagsInput } from '@mantine/core';

function Demo() {
  return (
    <Popover width={300} position="bottom" withArrow shadow="md">
      <Popover.Target>
        <Button>Toggle popover</Button>
      </Popover.Target>
      <Popover.Dropdown>
        <TagsInput
          label="Your favorite library"
          placeholder="Pick value or enter anything"
          data={['React', 'Angular', 'Vue', 'Svelte']}
          comboboxProps={{ withinPortal: false }}
        />
      </Popover.Dropdown>
    </Popover>
  );
}

Control dropdown opened state

You can control dropdown opened state with dropdownOpened prop. Additionally, you can use onDropdownClose and onDropdownOpen to listen to dropdown opened state changes.

import { TagsInput, Button } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';

function Demo() {
  const [dropdownOpened, { toggle }] = useDisclosure();
  return (
    <>
      <Button onClick={toggle} mb="md">
        Toggle dropdown
      </Button>

      <TagsInput
        label="Your favorite library"
        placeholder="Pick value or enter anything"
        data={['React', 'Angular', 'Vue', 'Svelte']}
        dropdownOpened={dropdownOpened}
      />
    </>
  );
}

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:

import { TagsInput } from '@mantine/core';

function Demo() {
  return (
    <TagsInput
      label="Your favorite library"
      placeholder="Pick value or enter anything"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      comboboxProps={{ position: 'top', middlewares: { flip: false, shift: false } }}
    />
  );
}

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.

import { TagsInput } from '@mantine/core';

function Demo() {
  return (
    <TagsInput
      label="Your favorite library"
      placeholder="Pick value or enter anything"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      comboboxProps={{ transitionProps: { transition: 'pop', duration: 200 } }}
    />
  );
}

Dropdown padding

import { TagsInput } from '@mantine/core';

function Demo() {
  return (
    <>
      <TagsInput
        label="Zero padding"
        placeholder="Pick value or enter anything"
        data={['React', 'Angular', 'Vue', 'Svelte']}
        comboboxProps={{ dropdownPadding: 0 }}
      />
      <TagsInput
        mt="md"
        label="10px padding"
        placeholder="Pick value or enter anything"
        data={['React', 'Angular', 'Vue', 'Svelte']}
        comboboxProps={{ dropdownPadding: 10 }}
      />
    </>
  );
}

Dropdown shadow

import { TagsInput } from '@mantine/core';

function Demo() {
  return (
    <TagsInput
      label="Your favorite library"
      placeholder="Pick value or enter anything"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      comboboxProps={{ shadow: 'md' }}
    />
  );
}

Left and right sections

TagsInput 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 – React node 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.
import { TagsInput, rem } from '@mantine/core';
import { IconComponents } from '@tabler/icons-react';

function Demo() {
  const icon = <IconComponents style={{ width: rem(16), height: rem(16) }} />;
  return (
    <>
      <TagsInput
        data={['React', 'Angular', 'Vue']}
        leftSectionPointerEvents="none"
        leftSection={icon}
        label="Your favorite library"
        placeholder="Your favorite library"
      />
      <TagsInput
        mt="md"
        data={['React', 'Angular', 'Vue']}
        rightSectionPointerEvents="none"
        rightSection={icon}
        label="Your favorite library"
        placeholder="Your favorite library"
      />
    </>
  );
}

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.

Input description

FirstSecond
Variant
Size
Radius
import { TagsInput } from '@mantine/core';

function Demo() {
  return (
    <TagsInput
      label="Input label"
      description="Input description"
      placeholder="TagsInput placeholder"
      value={['First', 'Second']}
      data={['React', 'Angular', 'Vue', 'Svelte']}
    />
  );
}

Read only

Set readOnly to make the input read only. When readOnly is set, TagsInput will not show suggestions and will not call onChange function.

FirstSecond
import { TagsInput } from '@mantine/core';

function Demo() {
  return (
    <TagsInput
      label="Read only"
      placeholder="Enter tag"
      readOnly
      defaultValue={['First', 'Second']}
    />
  );
}

Disabled

Set disabled to disable the input. When disabled is set, user cannot interact with the input and TagsInput will not show suggestions.

FirstSecond
import { TagsInput } from '@mantine/core';

function Demo() {
  return (
    <TagsInput
      label="Disabled"
      placeholder="Enter tag"
      disabled
      defaultValue={['First', 'Second']}
    />
  );
}

Error state

ReactAngular
ReactAngular

Invalid name

import { TagsInput } from '@mantine/core';

function Demo() {
  return (
    <>
      <TagsInput
        label="Boolean error"
        placeholder="Boolean error"
        error
        defaultValue={['React', 'Angular']}
      />
      <TagsInput
        mt="md"
        label="With error message"
        placeholder="With error message"
        error="Invalid name"
        defaultValue={['React', 'Angular']}
      />
    </>
  );
}

Styles API

TagsInput supports Styles API, you can add styles to any inner element of the component withclassNames prop. Follow Styles API documentation to learn more.

Description

FirstSecond

Component Styles API

Hover over selectors to highlight corresponding elements

/*
 * Hover over selectors to apply outline styles
 *
 */

Get element ref

import { useRef } from 'react';
import { TagsInput } from '@mantine/core';

function Demo() {
  const ref = useRef<HTMLInputElement>(null);
  return <TagsInput ref={ref} />;
}

Accessibility

If TagsInput is used without label prop, it will not be announced properly by screen reader:

import { TagsInput } from '@mantine/core';

// Inaccessible input – screen reader will not announce it properly
function Demo() {
  return <TagsInput />;
}

Set aria-label to make the input accessible. In this case label will not be visible, but screen reader will announce it:

import { TagsInput } from '@mantine/core';

// Accessible input – it has aria-label
function Demo() {
  return <TagsInput aria-label="My input" />;
}

If label prop is set, input will be accessible it is not required to set aria-label:

import { TagsInput } from '@mantine/core';

// Accessible input – it has associated label element
function Demo() {
  return <TagsInput label="My input" />;
}

To set aria-label on the clear button, use clearButtonProps. Note that it is required only when clearable is set.

import { TagsInput } from '@mantine/core';

function Demo() {
  return (
    <TagsInput
      data={[]}
      clearable
      clearButtonProps={{
        'aria-label': 'Clear input',
      }}
    />
  );
}

Previous

Select

Next

ActionIcon

Welcome to Mantine, React components library that you always wished for

Build fully functional accessible web applications faster than ever

About

ContributeAbout MantineChangelogReleases

Community

Chat on DiscordFollow on TwitterFollow on GithubGitHub discussions

Project

Mantine UIDocumentationGithub organizationnpm organization

Built by Vitaly Rtishchev and these awesome people