Базовый синтаксис инициализации

Работа с Choices.js начинается с привязки библиотеки к DOM-элементу формы. Основная идея заключается в том, что обычный <select> или <input> заменяется управляемым JavaScript-экземпляром, который расширяет стандартное поведение и добавляет поиск, мультивыбор, теги и управление списком опций.

Базовый объект библиотеки создаётся через конструктор:

new Choices(element, options);

Ключевым элементом здесь выступает element, который должен ссылаться на DOM-ноду.

Получение DOM-элемента

Перед инициализацией необходимо получить ссылку на элемент формы. Наиболее распространённый способ — использование querySelector:

const selectElement = document.querySelector('#my-select');

Также допустимо использование любых валидных селекторов:

const element = document.querySelector('.js-choice');

Важно, чтобы элемент существовал в DOM на момент инициализации. Часто это обеспечивается обработчиком загрузки страницы:

document.addEventListener('DOMContentLoaded', () => {
  const element = document.querySelector('#my-select');
});

Базовая инициализация экземпляра

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

const element = document.querySelector('#my-select');

const choices = new Choices(element);

В этом случае библиотека применяет стандартные настройки:

  • включён одиночный выбор (для <select>)
  • активирован поиск (если поддерживается типом элемента)
  • используются дефолтные классы и шаблоны отображения

Экземпляр сохраняется в переменной choices, что позволяет в дальнейшем управлять поведением компонента.

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

Choices.js позволяет передавать второй аргумент — объект конфигурации:

const choices = new Choices(element, {
  searchEnabled: true,
  removeItemButton: true,
  shouldSort: false
});

Структура объекта всегда плоская и описывает поведение компонента:

  • searchEnabled — включает или отключает поиск по списку
  • removeItemButton — добавляет кнопку удаления выбранного элемента
  • shouldSort — управляет сортировкой элементов

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

Работа с select и input

Choices.js автоматически определяет тип элемента.

Обычный select

<select id="my-select">
  <option value="1">Первый</option>
  <option value="2">Второй</option>
</select>
const choices = new Choices(document.querySelector('#my-select'));

В этом режиме библиотека заменяет стандартный dropdown на кастомный интерфейс.

Множественный выбор

Если у <select> указан атрибут multiple, Choices.js автоматически переключается в режим списка выбранных элементов:

<select id="tags" multiple>
  <option value="js">JavaScript</option>
  <option value="css">CSS</option>
</select>
const choices = new Choices(document.querySelector('#tags'), {
  removeItemButton: true
});

Каждый выбранный элемент становится отдельным “тегом”, который можно удалять.

Input с тегами

Choices.js поддерживает режим ввода произвольных значений:

<input id="tags-input" type="text">
const choices = new Choices(document.querySelector('#tags-input'), {
  delimiter: ',',
  editItems: true
});

В этом случае пользователь может вводить значения вручную, разделяя их символом ,.

Структура объекта экземпляра

После инициализации возвращается объект, содержащий методы управления:

const choices = new Choices(element);

Этот объект предоставляет доступ к:

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

Пример структуры использования:

choices.setValue(['value1']);
choices.clearStore();
choices.destroy();

Передача данных через JavaScript

Помимо HTML-разметки, список опций можно задавать программно:

const choices = new Choices(element, {
  choices: [
    { value: '1', label: 'Первый' },
    { value: '2', label: 'Второй' }
  ]
});

Каждый объект описывает отдельный элемент списка:

  • value — значение, отправляемое в форму
  • label — отображаемый текст
  • дополнительные параметры могут включать состояние выбора или отключения

Инициализация нескольких элементов

Choices.js не ограничивает количество экземпляров на странице. Каждый элемент создаётся отдельно:

document.querySelectorAll('.js-choice').forEach((el) => {
  new Choices(el);
});

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

Повторная инициализация и предотвращение дубликатов

Повторное создание экземпляра на одном и том же элементе приводит к конфликтам интерфейса. Для контроля используется сохранение ссылки:

const element = document.querySelector('#my-select');

if (!element.dataset.choicesInitialized) {
  new Choices(element);
  element.dataset.choicesInitialized = 'true';
}

Альтернативный подход — хранение экземпляра в переменной или структуре состояния приложения.

Инициализация с отключением части функциональности

Choices.js позволяет минимизировать функциональность для упрощённых интерфейсов:

const choices = new Choices(element, {
  searchEnabled: false,
  itemSelectText: '',
  shouldSort: false,
  removeItemButton: false
});

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

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

Критическим моментом является синхронизация с DOM. При работе с динамически загружаемыми компонентами инициализация выполняется после вставки элемента в документ:

function initSelect(container) {
  const element = container.querySelector('select');
  return new Choices(element);
}

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

Внутренний жизненный цикл экземпляра

После вызова конструктора происходят этапы:

  1. Чтение исходного DOM-элемента
  2. Построение внутреннего состояния списка
  3. Генерация кастомной разметки
  4. Подмена стандартного UI
  5. Привязка событий (click, input, keydown)

Именно на этапе инициализации формируется связка между исходным <select> и новым интерфейсом, который управляется через JavaScript API.

Оглавление