﻿---
description: Компонент для ввода и отображения множества значений.
tags: selection, search
---

# ChipsInput \[tag:component]

Компонент для ввода и отображения множества значений.
Позволяет пользователю добавлять, удалять и редактировать элементы списка.
Каждый элемент представлен в виде отдельного компонента `Chip`.

Связанные компоненты:

* [`Chip`](/components/chip)

```jsx
<ChipsInput
  defaultValue={[
    { value: 'red', label: 'Красный' },
    { value: 'blue', label: 'Синий' },
  ]}
  placeholder="Введите значение"
/>
```

## Режим работы

Компонент поддерживает работу как в неконтролируемом режиме, так и контролируемом. Это стандартное поведение
React-компонентов, прочитать про это можно в [документации React](https://react.dev/reference/react-dom/components/input#controlling-an-input-with-a-state-variable).

Для использования неконтролируемого режима достаточно просто *не* передавать `value` или передавать `defaultValue`, если
требуется задать значение по умолчанию.
Для контролируемого режима используйте связку свойств `value`/`onChange` для задания значения и его изменения.

```jsx
// Неконтролируемое состояние
<ChipsInput
  defaultValue={[
    {
      value: 'red',
      label: 'Красный',
    },
  ]}
/>;

// Контролируемое состояние
const [colors, setColors] = React.useState([]);

<ChipsInput value={colors} onChange={setColors} />;
```

## Управление вводом

### Разделитель

Задаётся свойством `delimiter`. Позволяет добавлять несколько элементов за раз, разделяя их указанным символом.

Представляет собой символ, который будет использоваться как разделитель для автоматического создания опций из текста,
введенного или вставленного в поле ввода. Например, при `delimiter=","` вставка текста "Красный,Синий" в поле ввода
создаст два элемента - "Красный" и "Синий".

Пока поддерживаются только строковые символы.

```jsx
<ChipsInput placeholder="Используйте запятую" delimiter="," />
```

### Потеря фокуса

По умолчанию при потере полем фокуса добавления в список опций не происходит.
С помощью свойства `addOnBlur` можно включить поведение, при котором потеря фокуса будет приводить к добавлению нового элемента.

```jsx
<ChipsInput
  defaultValue={[
    {
      value: 'red',
      label: 'Красный',
    },
  ]}
  placeholder="Введите значение"
  addOnBlur
/>
```

## Состояния

### `disabled`

Свойство `disabled` блокирует взаимодействие с компонентом и добавляет визуальную индикацию недоступности.

```jsx
<ChipsInput defaultValue={[{ value: 'red', label: 'Красный' }]} disabled />
```

## Валидация

Свойство `status` используется для визуализации валидации компонента - некорректности заполненного поля (значение `"error"`)
или успешной валидации (значение `"valid"`).

> Если вы используете `ChipsInput` вместе с [`FormItem`](/components/form-item), вам достаточно указать свойство `status` только у
> [`FormItem`](/components/form-item).

```jsx
<ChipsInput defaultValue={[{ value: 'red', label: 'Красный' }]} status="error" />
<ChipsInput defaultValue={[{ value: 'green', label: 'Зелёный' }]} status="valid" />
```

## Кастомизация

### Визуальное оформление

С помощью свойства `renderChip` можно влиять на отображение конкретного значения. Вы можете изменить
стандартный компонент `Chip` или использовать свой компонент:

```jsx
<ChipsInput
  defaultValue={[
    {
      value: '1',
      label: 'Алексей',
      src: 'https://avatars.githubusercontent.com/u/91548592?s=50',
    },
    { value: '2', label: 'Никита', src: 'https://avatars.githubusercontent.com/u/32414396?s=50' },
  ]}
  renderChip={({ value, label, ...rest }, { src }) => (
    <Chip value={value} before={<Avatar src={src} size={20} aria-hidden />} {...rest}>
      {label}
    </Chip>
  )}
/>
```

Важно отметить, что первым параметром в обработчике `renderChip` идёт объект со свойствами, необходимыми для
корректной работы `a11y`. Если для отображения опции вы используете свой компонент, убедитесь, что все эти свойства
компонент получает и корректно обрабатывает. Вторым параметром идёт объект со значением конкретной опции
(значение, переданное в `value`/`defaultValue`).

## slotProps

Через свойство `slotProps` можно прокинуть свойства во внутренние элементы.
Это удобно для добавления кастомных классов, data-атрибутов, aria-атрибутов, обработчиков событий, доступов к элементам через `getRootRef` и других расширений, не влияя на внешний API компонента.

```jsx
const inputRef = React.useRef();

return (
  <ChipsInput
    defaultValue={[
      { value: 'red', label: 'Красный' },
      { value: 'blue', label: 'Синий' },
    ]}
    placeholder="Введите значение"
    className="my-root-class"
    data-testid="chips-input-root"
    id="colors-input-id"
    slotProps={{
      root: {
        id: 'chips-input-root-id',
      },
      input: {
        className: 'my-input-class',
        'aria-label': 'Пример slotProps',
        getRootRef: inputRef,
      },
    }}
  />
)
```

## Доступность (a11y) \[#a11y]

Компонент обеспечивает базовую доступность через стандартные `HTML`-атрибуты и `ARIA`-роли.

Для улучшения доступности рекомендуется связывать компонент с текстовым описанием одним из следующих способов:

* обернуть в `<label>`;

  ```jsx
  <label>
    Список исполнителей
    <ChipsInput placeholder="Введите название" />
  </label>
  ```

* указать `id` или `aria-describedby` и передать в `<label>` или [`FormItem`](/components/form-item) через `htmlFor`;

  ```jsx
  <label htmlFor="chips">Список исполнителей</label>
  <ChipsInput placeholder="Введите название" id="chips"/>
  ```

  ```jsx
  <FormItem top="Список исполнителей" htmlFor="chips">
    <ChipsInput placeholder="Введите название" id="chips" />
  </FormItem>
  ```

* указать `aria-label`;

  ```jsx
  <ChipsInput placeholder="Введите название" aria-label="Список исполнителей" />
  ```

При необходимости, через свойство `chipsListLabel` можете указать описания списка выбранных опций.

## Свойства и методы \[#api]

| Свойство            | Тип                                                                                                                                                                                              | По умолчанию                  | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `addOnBlur`         | `boolean`                                                                                                                                                                                        | `-`                           | Добавляет значение в список на событие `onBlur`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `after`             | `ReactNode`                                                                                                                                                                                      | `-`                           | Добавляет иконку справа.  Рекомендации:  - Используйте следующие размеры иконок `12` \| `16` \| `20` \| `24` \| `28`. - Используйте [IconButton](https://vkui.io/components/icon-button), если вам нужна иконка, реагируюущая на нажатие.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `align`             | `AlignType`                                                                                                                                                                                      | `-`                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `allowClearButton`  | `boolean`                                                                                                                                                                                        | `-`                           | Если `true`, то справа будет отображаться кнопка для очистки значения.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `before`            | `ReactNode`                                                                                                                                                                                      | `-`                           | Добавляет иконку слева.  Рекомендации:  - Используйте следующие размеры иконок `12` \| `16` \| `20` \| `24` \| `28`. - Используйте [IconButton](https://vkui.io/components/icon-button), если вам нужна иконка, реагирующая на нажатие.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `chipsListLabel`    | `string`                                                                                                                                                                                         | `-`                           | `aria-label` для списка выбранных опций.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `ClearButton`       | `ComponentType<FormFieldClearButtonProps>`                                                                                                                                                       | `-`                           | Кастомная кнопка для очистки значения. Должна принимать обязательное свойство `onClick`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `clearButtonShown`  | `boolean`                                                                                                                                                                                        | `-`                           | Показывать ли кнопку для очистки значения.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `clearButtonTestId` | `string`                                                                                                                                                                                         | `-`                           | (e2e) testId кнопки очистки.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `defaultInputValue` | `string`                                                                                                                                                                                         | `-`                           | Значение поля ввода по умолчанию.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `defaultValue`      | `Option[]`                                                                                                                                                                                       | `-`                           | Выбранные опции по умолчанию.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `delimiter`         | `string \| RegExp \| string[]`                                                                                                                                                                   | `-`                           | Символ или строка, которая будет использоваться как разделитель для автоматического создания опций из текста, введенного в поле ввода. Принимает: - `string` - простая строка - `RegExp` - регулярное выражение - `string[]` - массив строк, по которым нужно разелять ввод.  Работает в двух сценариях: 1. При вводе разделителя - текст до разделителя автоматически преобразуется в новую опцию.    Например, при `delimiter=","` ввод "опция1," создаст опцию "опция1".  2. При вставке из буфера обмена - если вставляемый текст содержит разделители,    он будет автоматически разбит на несколько опций.    Например, при `delimiter=","` вставка "опция1,опция2,опция3" создаст    три отдельные опции: "опция1", "опция2" и "опция3". |
| `disabled`          | `boolean`                                                                                                                                                                                        | `-`                           | Блокировка взаимодействия с компонентом.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `getNewOptionData`  | `GetNewOptionData<Option>`                                                                                                                                                                       | `-`                           | Функция для создания новой опции.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `getOptionLabel`    | `GetOptionLabel<Option>`                                                                                                                                                                         | `-`                           | Селектор пользовательского представления.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `getOptionValue`    | `GetOptionValue<Option>`                                                                                                                                                                         | `-`                           | Селектор значения.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `getRef`            | `Ref<HTMLInputElement>`                                                                                                                                                                          | `-`                           | **Deprecated**: Since 7.9.0. Вместо этого используйте `slotProps={ input: { getRootRef: ... } }`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `getRootRef`        | `Ref<HTMLDivElement>`                                                                                                                                                                            | `-`                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `inputValue`        | `string`                                                                                                                                                                                         | `-`                           | Значение поля ввода.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `maxHeight`         | `number`                                                                                                                                                                                         | `-`                           | Максимальная высота поля.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `mode`              | `"default" \| "plain"`                                                                                                                                                                           | `-`                           | Режим отображения.  - `default` — показывает фон, обводку и, при наличии, текст-подсказку. - `plain` — показывает только текст-подсказку.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `onChange`          | `OnChange<Option>`                                                                                                                                                                               | `-`                           | Обработчик изменения выбранных опций.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `onInputChange`     | `OnInputChange`                                                                                                                                                                                  | `-`                           | Обработчик изменения значения в поле ввода.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `ref`               | `Ref<HTMLDivElement>`                                                                                                                                                                            | `-`                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `renderChip`        | `RenderChip<Option>`                                                                                                                                                                             | `Используется [Chip](#/Chip)` | Render prop функция для возврата своего компонента.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `slotProps`         | `{ root?: (HTMLAttributes<HTMLDivElement> & HasRootRef<HTMLDivElement> & HasDataAttribute); input?: (InputHTMLAttributes<...> & ... 1 more ... & HasDataAttribute) \| undefined; } \| undefined` | `-`                           | Свойства, которые можно прокинуть внутрь компонента: - `root`: свойства для прокидывания в корень компонента; - `input`: свойства для прокидывания в поле ввода.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `status`            | `"default" \| "error" \| "valid"`                                                                                                                                                                | `-`                           | Статус отображения поля в форме.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `value`             | `Option[]`                                                                                                                                                                                       | `-`                           | Выбранные опции.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
