Простейший пример инициализации

Минимальный пример подключения библиотеки строится вокруг замены стандартного <select>-элемента на управляемый компонент с расширенными возможностями поиска, выбора и кастомизации. Базовая инициализация требует всего двух шагов: подключение ресурсов и вызов конструктора TomSelect.

Подключение библиотеки и зависимостей

Перед созданием экземпляра необходимо подключить CSS и JavaScript. В простейшем варианте через CDN:

<link href="https://cdn.jsdelivr.net/npm/tom-select/dist/css/tom-select.default.min.css" rel="stylesheet">

<script src="https://cdn.jsdelivr.net/npm/tom-select/dist/js/tom-select.complete.min.js"></script>

CSS отвечает за внешний вид выпадающего списка, поля ввода и выбранных элементов. JS-файл содержит всю логику: фильтрацию, обработку событий, рендеринг и управление состоянием.

HTML-разметка базового select

Для инициализации используется стандартный элемент select. Минимальная структура:

<select id="fruit-select">
  <option value="apple">Яблоко</option>
  <option value="banana">Банан</option>
  <option value="orange">Апельсин</option>
</select>

Ключевой момент — библиотека работает поверх существующего DOM-элемента, не требуя изменения семантики HTML.

Простая инициализация через JavaScript

Создание экземпляра выполняется вызовом конструктора TomSelect:

new TomSelect("#fruit-select");

После выполнения этого кода стандартный <select> заменяется на интерактивный компонент:

  • появляется поле поиска;
  • список становится фильтруемым;
  • выбор опций происходит через кастомный UI;
  • сохраняется синхронизация со значением исходного элемента.

Сохранение и синхронизация значения

Одной из особенностей базовой инициализации является автоматическое управление состоянием. Значение выбранного элемента остаётся связанным с оригинальным <select>.

Пример получения значения:

const select = new TomSelect("#fruit-select");

console.log(select.getValue());

Метод getValue() возвращает текущее значение, соответствующее value выбранной <option>.

Инициализация с опциями

Даже в простейшем случае допускается передача конфигурационного объекта. Это позволяет управлять поведением без изменения HTML.

new TomSelect("#fruit-select", {
  create: false,
  sortField: "text"
});

Основные параметры:

  • create — разрешает добавление новых значений пользователем;
  • sortField — определяет сортировку списка;
  • maxItems — ограничивает количество выбранных элементов;
  • placeholder — задаёт текст подсказки.

Работа с placeholder

Стандартный HTML-атрибут placeholder не всегда даёт ожидаемый результат, поэтому используется конфигурация:

new TomSelect("#fruit-select", {
  placeholder: "Выберите фрукт"
});

Если в <select> есть пустое значение, оно может использоваться как стартовое состояние:

<option value="">-- выберите --</option>

Инициализация мультивыбора

При использовании атрибута multiple поведение автоматически изменяется:

<select id="multi-select" multiple>
  <option value="html">HTML</option>
  <option value="css">CSS</option>
  <option value="js">JavaScript</option>
</select>
new TomSelect("#multi-select");

В этом режиме:

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

Работа с уже существующим значением

Если в HTML заранее задано выбранное значение, библиотека корректно его подхватывает:

<option value="banana" selected>Банан</option>

После инициализации это значение становится активным без дополнительных действий.

Доступ к экземпляру и управлению

Экземпляр TomSelect можно сохранить в переменную для дальнейшего управления:

const ts = new TomSelect("#fruit-select");

Доступные методы:

ts.addItem("apple");
ts.removeItem("banana");
ts.clear();
ts.clearOptions();

Даже в простейшей конфигурации это позволяет динамически изменять состояние компонента.

Удаление и повторная инициализация

При необходимости компонент можно уничтожить:

ts.destroy();

После вызова:

  • DOM возвращается к исходному состоянию;
  • оригинальный <select> снова становится активным;
  • обработчики событий удаляются.

Повторная инициализация возможна без перезагрузки страницы:

new TomSelect("#fruit-select");

Типичные ошибки при первой инициализации

Несмотря на простоту, базовое использование часто сопровождается рядом проблем:

1. Отсутствие подключения CSS

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

2. Инициализация до загрузки DOM

new TomSelect("#fruit-select");

Если элемент ещё не существует, инициализация не сработает. Корректный вариант:

document.addEventListener("DOMContentLoaded", () => {
  new TomSelect("#fruit-select");
});

3. Неверный селектор

Ошибки в id или классе приводят к тому, что библиотека не находит элемент и не создаёт экземпляр.

Поведение при пустом select

Если <select> не содержит <option>, компонент всё равно создаётся, но список остаётся пустым. В этом случае логика поиска и выбора не активируется до появления данных.

Базовая модель работы внутри

На уровне архитектуры инициализация выполняет несколько действий:

  • клонирование состояния <select>;
  • создание скрытого input для управления вводом;
  • построение dropdown-структуры;
  • привязка событий клавиатуры и мыши;
  • синхронизация значений между UI и DOM.

Эта модель позволяет использовать компонент как замену стандартного select без потери совместимости с формами.

Минимальный рабочий шаблон

<link href="https://cdn.jsdelivr.net/npm/tom-select/dist/css/tom-select.default.min.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/tom-select/dist/js/tom-select.complete.min.js"></script>

<select id="fruit-select">
  <option value="apple">Яблоко</option>
  <option value="banana">Банан</option>
  <option value="orange">Апельсин</option>
</select>

<script>
  document.addEventListener("DOMContentLoaded", () => {
    new TomSelect("#fruit-select");
  });
</script>
Оглавление