Полный список опций

Tom Select конфигурируется через единый объект опций, который передаётся при инициализации экземпляра. Архитектура настроек построена вокруг расширяемой модели: базовые параметры управляют данными и поведением, отдельные группы отвечают за поиск, создание элементов, рендеринг, работу с удалёнными источниками и плагинами.

options

Массив исходных элементов, доступных для выбора. Каждый элемент обычно представлен объектом.

options: [
  { id: 1, title: "Москва" },
  { id: 2, title: "Санкт-Петербург" }
]

items

Массив значений, выбранных по умолчанию.

items: [1]

valueField

Поле объекта, используемое как значение элемента.

valueField: "id"

labelField

Поле, отображаемое в интерфейсе.

labelField: "title"

optgroupField

Поле, определяющее принадлежность к группе.

optgroupField: "category"

Настройки группировки

optgroups

Массив групп для структурирования списка.

optgroups: [
  { value: "cities", label: "Города" },
  { value: "countries", label: "Страны" }
]

optgroupLabelField

Поле названия группы.

optgroupLabelField: "label"

optgroupValueField

Поле идентификатора группы.

optgroupValueField: "value"

optgroupOrder

Определяет порядок группировки (массив значений или функция).

optgroupOrder: ["countries", "cities"]

Поиск и фильтрация

searchField

Поле или массив полей, по которым выполняется поиск.

searchField: ["title", "description"]

score

Функция ранжирования результатов поиска.

score: function(search) {
  return function(item) {
    return item.title.includes(search) ? 1 : 0;
  };
}

shouldLoad

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

shouldLoad: function(query) {
  return query.length > 2;
}

loadThrottle

Задержка между запросами загрузки (в мс).

loadThrottle: 300

maxOptions

Максимальное количество отображаемых элементов.

maxOptions: 100

highlight

Включает подсветку совпадений.

highlight: true

Поведение интерфейса

placeholder

Текст-заполнитель.

placeholder: "Выберите значение"

openOnFocus

Открытие списка при фокусе.

openOnFocus: true

closeAfterSelect

Закрытие списка после выбора элемента.

closeAfterSelect: false

hideSelected

Скрытие уже выбранных элементов из списка.

hideSelected: true

maxItems

Максимальное количество выбранных элементов.

maxItems: 3

allowEmptyOption

Разрешение пустого значения.

allowEmptyOption: false

Создание новых элементов

create

Разрешает создание новых опций на лету.

create: true

createOnBlur

Создание элемента при потере фокуса.

createOnBlur: true

createFilter

Функция фильтрации создаваемых значений.

createFilter: function(input) {
  return input.length > 1;
}

persist

Сохранение созданных элементов между сессиями.

persist: true

Загрузка данных (AJAX и динамика)

load

Функция загрузки данных по запросу.

load: function(query, callback) {
  fetch(`/api?q=${query}`)
    .then(res => res.json())
    .then(callback);
}

preload

Загрузка данных при инициализации.

  • "true" — всегда
  • "focus" — при фокусе
  • "false" — отключено
preload: "focus"

Рендеринг интерфейса

render

Объект шаблонов элементов интерфейса.

render: {
  option: function(data, escape) {
    return `<div>${escape(data.title)}</div>`;
  },
  item: function(data, escape) {
    return `<div>${escape(data.title)}</div>`;
  }
}

escape

Функция экранирования HTML (может переопределяться).

Поведение выбора

selectOnTab

Выбор элемента по нажатию Tab.

selectOnTab: true

selectOnBlur

Автоматический выбор при потере фокуса.

selectOnBlur: false

delimiter

Разделитель при множественном вводе.

delimiter: ","

Производительность и ограничения

maxOptions

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

loadThrottle

Регулирование частоты запросов.

sortField

Поле сортировки элементов.

sortField: "title"

Поведение поиска и совпадений

searchConjunction

Логика объединения поисковых терминов.

  • "and"
  • "or"
searchConjunction: "and"

firstUrl

Автопереход по первому результату (используется редко).

Работа с состоянием

onInitialize

Колбэк инициализации.

onInitialize: function() {
  console.log("init");
}

onChange

Срабатывает при изменении выбора.

onChange: function(value) {
  console.log(value);
}

onItemAdd

Добавление элемента.

onItemAdd: function(value) {}

onItemRemove

Удаление элемента.

onItemRemove: function(value) {}

Подключение плагинов

plugins

Список расширений поведения.

plugins: ["remove_button", "dropdown_input"]

Расширения влияют на UI и поведение без изменения основной логики.

Дополнительные параметры

controlInput

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

controlInput: true

openOnCreate

Открытие списка после создания элемента.

openOnCreate: true

DOM-узел для рендера выпадающего списка.

dropdownParent: document.body

load + shouldLoad взаимодействие

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

Конфигурационная модель

Структура опций Tom Select построена так, что каждый параметр влияет на отдельный слой поведения:

  • слой данных (options, items, valueField)
  • слой поиска (searchField, score, highlight)
  • слой интерфейса (render, placeholder, dropdownParent)
  • слой взаимодействия (create, maxItems, closeAfterSelect)
  • слой интеграции (load, plugins, callbacks)

Такое разделение позволяет комбинировать параметры без конфликтов и формировать поведение компонента через декларативную конфигурацию.

Оглавление