Полный список опций конфигурации

searchEnabled Управляет включением встроенного поиска по списку элементов. Тип: boolean По умолчанию: true

При значении false поле поиска скрывается, а фильтрация по вводу пользователя отключается полностью. Это используется для простых селектов, где список небольшой и поиск не требуется.

searchChoices Определяет, будут ли учитываться элементы списка при поиске. Тип: boolean По умолчанию: true

Если отключить параметр, поиск будет работать только по уже выбранным элементам (в мультиселектах).

searchFloor Минимальное количество символов для запуска поиска. Тип: number По умолчанию: 1

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

searchResultLimit Максимальное количество отображаемых результатов поиска. Тип: number По умолчанию: 4

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

silent Отключает часть внутренних событий и логики обновления. Тип: boolean По умолчанию: false

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

Управление выбором и добавлением элементов

removeItemButton Включает кнопку удаления выбранного элемента. Тип: boolean По умолчанию: false

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

duplicateItemsAllowed Разрешает добавление одинаковых значений. Тип: boolean По умолчанию: true

При значении false предотвращает повторный выбор одного и того же элемента.

addItems Разрешает добавление пользовательских значений, отсутствующих в списке. Тип: boolean По умолчанию: true

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

addItemFilter Функция-фильтр для добавляемых вручную элементов. Тип: function

Позволяет валидировать ввод перед добавлением в список. Часто применяется для проверки длины строки или формата (например, email).

editItems Позволяет редактировать уже добавленные элементы. Тип: boolean По умолчанию: false

При включении пользователь может изменять значение выбранного элемента прямо в интерфейсе.

maxItemCount Максимальное количество выбранных элементов. Тип: number По умолчанию: -1 (без ограничений)

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

maxItemText Текст, отображаемый при достижении лимита выбора. Тип: function или string

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

Настройки сортировки и структуры данных

shouldSort Определяет необходимость сортировки элементов. Тип: boolean По умолчанию: true

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

shouldSortItems Контролирует сортировку уже выбранных элементов. Тип: boolean По умолчанию: false

Позволяет сохранить порядок выбора пользователя, что важно для сценариев приоритизации.

sortFn Пользовательская функция сортировки. Тип: function

Позволяет реализовать сложную логику сортировки, например, по весу, популярности или локализации.

delimiter Разделитель для строкового представления выбранных значений. Тип: string По умолчанию: ','

Используется при сериализации значений в input.

Тексты интерфейса и пользовательские сообщения

placeholderValue Текст placeholder для пустого состояния. Тип: string

Отображается в поле выбора до первого взаимодействия пользователя.

searchPlaceholderValue Placeholder для поля поиска. Тип: string

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

noResultsText Сообщение при отсутствии результатов поиска. Тип: string По умолчанию: "No results found"

Используется при пустой выдаче фильтрации.

noChoicesText Сообщение, когда список полностью пуст. Тип: string По умолчанию: "No choices to choose from"

Отличается от noResultsText тем, что относится к отсутствию данных вообще.

itemSelectText Подсказка для выбора элемента. Тип: string По умолчанию: "Press to select"

Отображается при наведении или фокусе на элемент списка.

loadingText Текст загрузки при асинхронной подгрузке данных. Тип: string По умолчанию: "Loading..."

Используется при динамической загрузке через API.

Настройки визуального отображения и поведения UI

allowHTML Разрешает использование HTML внутри значений и подписей. Тип: boolean По умолчанию: true

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

classNames Объект для переопределения CSS-классов. Тип: object

Позволяет полностью адаптировать внешний вид компонента под дизайн-систему проекта. Обычно содержит ключи вроде containerOuter, containerInner, item, choice, highlightedState.

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

Используется для оптимизации рендеринга при больших объемах данных.

Настройки поиска и алгоритмов фильтрации

fuseOptions Объект конфигурации для библиотеки fuzzy-поиска. Тип: object

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

Пример ключевых параметров внутри:

  • threshold — уровень строгости поиска
  • distance — допустимая дистанция совпадения
  • keys — поля объектов, участвующие в поиске

Поведенческие колбэки и хуки

callbackOnInit Функция, вызываемая после инициализации компонента. Тип: function

Используется для выполнения логики после полной готовности UI.

callbackOnCreateTemplates Позволяет переопределить или расширить шаблоны рендеринга. Тип: function

Предоставляет доступ к внутренним шаблонам Choices.js и позволяет кастомизировать структуру DOM.

Работа с данными и форматом элементов

Choices.js ожидает элементы в стандартной структуре:

  • value — значение элемента
  • label — отображаемый текст
  • selected — состояние выбора
  • disabled — недоступность элемента
  • customProperties — дополнительные пользовательские данные

Эти поля тесно связаны с поведением большинства опций: сортировкой, фильтрацией, отображением и кастомизацией UI.

Параметры производительности и оптимизации

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

  • searchFloor для ограничения частоты поиска
  • searchResultLimit для ограничения DOM-элементов
  • renderChoiceLimit для контроля рендера

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

Поведение при взаимодействии пользователя

Компонент учитывает несколько внутренних сценариев:

  • ввод текста активирует фильтрацию при searchEnabled
  • выбор элемента зависит от duplicateItemsAllowed
  • добавление новых значений регулируется addItems
  • изменение состояния списка синхронизируется с input через delimiter

Эти механизмы работают совместно, формируя единый поток управления состоянием без необходимости внешнего state-менеджера.

Особенности конфигурации в реальных сценариях

При использовании в формах с серверной валидацией ключевое значение приобретают:

  • maxItemCount для ограничения выбора
  • addItemFilter для первичной валидации
  • fuseOptions для адаптивного поиска
  • shouldSortItems для сохранения пользовательского порядка

В сценариях автодополнения и API-подгрузки критичны:

  • searchFloor
  • searchResultLimit
  • loadingText
  • renderChoiceLimit

Эти параметры обеспечивают баланс между отзывчивостью интерфейса и нагрузкой на браузер.

Оглавление