Настройка режима multiple

Режим multiple предназначен для преобразования стандартного HTML <select> в компонент, поддерживающий выбор нескольких значений с расширенной логикой управления, поиском и визуализацией выбранных элементов. В контексте Tom Select данный режим является базовым механизмом построения теговых интерфейсов, фильтров и сложных форм с множественными значениями.

Включение режима multiple на уровне HTML

Основой активации множественного выбора выступает стандартный атрибут multiple у элемента <select>:

<select id="tags" multiple>
  <option value="js">JavaScript</option>
  <option value="ts">TypeScript</option>
  <option value="css">CSS</option>
</select>

При наличии атрибута multiple библиотека автоматически переводит компонент в режим работы с массивом значений.

Инициализация Tom Select в multiple-режиме

new TomSelect("#tags", {
  plugins: [],
});

При инициализации на элементе с multiple библиотека начинает хранить значение не как строку, а как массив строковых идентификаторов.

Структура данных в multiple-режиме

В режиме множественного выбора внутреннее значение представляется массивом:

["js", "css", "ts"]

Каждое добавление или удаление элемента изменяет состояние массива, что напрямую отражается на DOM и скрытом input.

Работа с выбором значений

Добавление значения

Добавление выполняется через API:

const control = document.querySelector("#tags").tomselect;

control.addItem("js");

Если значение уже присутствует, повторное добавление игнорируется, предотвращая дублирование.

Удаление значения

control.removeItem("css");

Удаление влияет на внутренний массив и обновляет визуальные теги.

Полная установка значений

control.setValue(["js", "ts"]);

Метод полностью перезаписывает текущее состояние.

Получение значений

control.getValue();

Возвращает массив выбранных значений.

Отображение выбранных элементов

В multiple-режиме выбранные элементы отображаются как отдельные UI-блоки (теги). Каждый элемент:

  • содержит label
  • имеет кнопку удаления
  • синхронизирован с внутренним состоянием

Визуализация формируется через шаблон render.item.

new TomSelect("#tags", {
  render: {
    item(data) {
      return `<div class="item">${data.text}</div>`;
    }
  }
});

Поведение input и отправка формы

Tom Select автоматически синхронизирует значение с скрытым <input>.

При multiple-режиме создаётся несколько значений с одинаковым name:

<input type="hidden" name="tags[]" value="js">
<input type="hidden" name="tags[]" value="ts">

Использование [] в имени поля критично для корректной обработки на сервере.

Ограничение количества выбранных элементов

Параметр maxItems управляет верхним пределом:

new TomSelect("#tags", {
  maxItems: 3
});

При достижении лимита:

  • скрывается возможность выбора новых элементов
  • поиск продолжает работать, но добавление блокируется

Поведение при создании новых значений

При включённой опции create допускается добавление пользовательских значений:

new TomSelect("#tags", {
  multiple: true,
  create: true
});

В multiple-режиме новые элементы сразу становятся частью массива значений.

Сортировка выбранных элементов

Порядок хранения значений зависит от последовательности добавления. Управление возможно через onItemAdd:

new TomSelect("#tags", {
  onItemAdd(value) {
    console.log("Добавлено:", value);
  }
});

Для принудительной сортировки применяется переустановка массива:

control.setValue(control.getValue().sort());

Очистка всех значений

control.clear();

Действие полностью сбрасывает состояние multiple-выбора.

Заблокированное состояние

control.lock();

В locked-режиме:

  • невозможно добавлять элементы
  • невозможно удалять элементы
  • UI становится неактивным

Разблокировка:

control.unlock();

События multiple-режима

Основные события:

addItem

Срабатывает при добавлении значения:

onItemAdd(value, item) {}

removeItem

onItemRemove(value) {}

change

Срабатывает при любом изменении массива:

onChange(valueArray) {}

Работа с optgroups в multiple-режиме

Множественный выбор поддерживает группировку:

<optgroup label="Frontend">
  <option value="react">React</option>
  <option value="vue">Vue</option>
</optgroup>

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

Ограничение повторов и уникальность

Tom Select гарантирует уникальность значений внутри массива. Логика:

  • проверка наличия перед добавлением
  • игнорирование повторных вставок
  • синхронизация с DOM без конфликтов

Работа с удалением через клавиатуру

При фокусе на input:

  • Backspace удаляет последний элемент
  • Delete удаляет выделенный элемент (при наличии фокуса)
  • Навигация между тегами осуществляется стрелками

Фильтрация и поиск при multiple

Поиск применяется к выпадающему списку, но не влияет на уже выбранные значения. Это позволяет:

  • искать среди всех доступных опций
  • независимо управлять текущим массивом выбора

Динамическое изменение списка значений

При обновлении источника данных:

control.addOption({ value: "node", text: "Node.js" });

или массово:

control.addOptions([
  { value: "node", text: "Node.js" },
  { value: "deno", text: "Deno" }
]);

multiple-режим автоматически интегрирует новые значения в доступный список без изменения уже выбранных элементов.

Особенности сериализации состояния

При использовании JSON-логики или AJAX отправки:

JSON.stringify(control.getValue());

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

Типичные ограничения multiple-режима

  • невозможность хранения сложных объектов без кастомного valueField
  • необходимость контроля размера массива при большом числе элементов
  • потенциальная перегрузка UI при большом количестве тегов
  • необходимость оптимизации рендера при динамических обновлениях

Управление placeholder в multiple

Placeholder отображается только при пустом массиве:

new TomSelect("#tags", {
  placeholder: "Выбор технологий"
});

После добавления первого элемента placeholder скрывается автоматически.

Оглавление