Загрузка исходных файлов

Самый быстрый способ начать работу с библиотекой — подключение через CDN. В этом случае не требуется установка зависимостей и настройка сборщика.

Для корректной работы необходимо подключить CSS и JavaScript файлы:

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

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

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

Инициализация выполняется после загрузки DOM:

<sel ect id="select">
  <option value="1">JavaScript</option>
  <option value="2">TypeScript</option>
</select>

<script>
  new TomSelect("#select", {
    create: false,
    sortField: "text"
  });
</script>

Ключевой момент заключается в том, что при использовании CDN класс TomSelect становится доступным глобально, без импортов и дополнительных конфигураций.

Установка через npm

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

npm install tom-select

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

Импорт в ES Modules

В современных проектах с поддержкой ES Modules используется прямой импорт:

import TomSelect fr om "tom-select";
import "tom-select/dist/css/tom-select.css";

Инициализация:

const sel ect = new TomSelect("#select", {
  maxItems: 3,
  create: true
});

Особенность данного подхода заключается в том, что стили импортируются отдельно. Это позволяет сборщику (например, Vite или Webpack) включать их в общий бандл или выделять в отдельный CSS-файл.

Использование в CommonJS

В старых проектах Node.js или при использовании Webpack без ES Modules возможен импорт через require:

const TomSelect = require("tom-select");
require("tom-select/dist/css/tom-select.css");

Инициализация не отличается:

const sel ect = new TomSelect("#select", {
  plugins: ["remove_button"]
});

Несмотря на поддержку CommonJS, предпочтительным остаётся ES Modules как более современный стандарт.

Подключение в сборщиках (Vite, Webpack, Parcel)

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

Vite

import TomSelect fr om "tom-select";
import "tom-select/dist/css/tom-select.css";

new TomSelect("#select");

Vite автоматически обрабатывает CSS импорт и включает стили в итоговую сборку.

Webpack

Webpack требует наличия css-loader и style-loader:

npm install css-loader style-loader --save-dev

Конфигурация:

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ["style-loader", "css-loader"]
      }
    ]
  }
};

Импорт:

import TomSelect fr om "tom-select";
import "tom-select/dist/css/tom-select.css";

Parcel

Parcel не требует дополнительной конфигурации. Достаточно импортировать модуль и стили:

import TomSelect from "tom-select";
import "tom-select/dist/css/tom-select.css";

Подключение только JavaScript без CSS

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

import TomSelect from "tom-select";

В этом случае необходимо самостоятельно реализовать стилизацию компонентов:

  • контейнер селекта
  • выпадающий список
  • активные и выбранные элементы
  • состояния hover и focus

Отсутствие CSS не влияет на функциональность, но полностью убирает визуальную составляющую.

Различия между полной и облегчённой сборкой

В пакете доступны разные варианты сборки:

  • tom-select.complete.js — включает все плагины и расширения
  • tom-select.js — базовая версия без части дополнительных модулей

Использование полной сборки через CDN:

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

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

import TomSelect from "tom-select";

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

Подключение через локальные файлы

Возможен вариант ручной загрузки файлов из node_modules или скачанного архива.

<link rel="stylesheet" href="/assets/tom-select.css">
<script src="/assets/tom-select.js"></script>

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

Инициализация после загрузки ресурсов

При подключении через script-тег важно учитывать порядок загрузки:

<script src="tom-select.js"></script>
<script>
  document.addEventListener("DOMContentLoaded", () => {
    new TomSelect("#select");
  });
</script>

Если скрипт подключён с defer, необходимость в обработчике DOMContentLoaded исчезает:

<script src="tom-select.js" defer></script>

Подключение в динамических приложениях

В SPA (React, Vue, Svelte) библиотека подключается как обычный модуль, но инициализация должна выполняться после монтирования DOM-элемента.

Пример логики:

import TomSelect from "tom-select";

function initSelect() {
  new TomSelect("#select");
}

window.addEventListener("load", initSelect);

В компонентах важно уничтожать экземпляры при размонтировании, чтобы избежать утечек памяти:

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

ts.destroy();

Типичные ошибки при загрузке

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

  • отсутствие CSS-файла приводит к «сломленному» интерфейсу
  • двойная инициализация вызывает дублирование элементов
  • подключение скрипта до загрузки DOM приводит к null-селектору
  • смешивание разных версий пакета вызывает конфликты API

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

Оглавление