Form controls: Custom select

Вступление #

Для кастомизации селекта можно использовать класс .js-select по умолчанию и стандартную разметку.

Выпадающий список селекта реализован на базе Headless Tippy.

Установка #

Пример разметки и инициализации кастомизированного селекта.

    <select class="js-select">
        <option placeholder>Выберите фрукт</option>
        <option>Яблоко</option>
        <option>Апельсин</option>
        <option>Арбуз</option>
    </select>

	const options = {
		'notfound': 'Увы, ничего не нашли',
		'placeholder': {
			'output': 'Список для выбора',
			'search': 'Искать',
		},
		'tippy': {
			'offset': [10, 10],
		},
		'addClass': 'my-custom-select',
	};

    BasicSelect.init('.my-select', options);
    BasicSelect.init(document.querySelector('.my-select'), options);
    BasicSelect.init(document.querySelectorAll('.my-select'), options);

    // или

    BasicSelect.init(); // по умолчанию инициaлизирует элементы с классом .js-select

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

Настройки, заданные с использованием data-атрибутов.

data-select-options #

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

    <select
        class="js-select"
        data-select-options='{
            "enabledSearch": true,
            "notfound": "Увы, ничего не нашли",
            "placeholder": {
                "output": "Список для выбора",
                "search": "Искать"
            },
            "addClass": "my-custom-select"
        }'
    >
        <option placeholder>Выберите фрукт</option>
        <option>Яблоко</option>
        <option>Апельсин</option>
        <option>Арбуз</option>
    </select>

Параметры:

Название	Тип	Описание
`enabledSearch`	`boolean`	Показать поиск, по умолчанию — `true`.
`notfound`	`string`	Текст при нулевом результате поиска, по умолчанию — `ничего не найдено`.
`placeholder.output`	`string`	Текст-заглушка для вывода результата, по умолчанию — `Выберите из списка`.
`placeholder.search`	`string`	Текст-заглушка для поля поиска, по умолчанию — `Найти`.
`tippy`	`object`	В значениях указываются параметры для гибкой настройки выпадающего списка, с ними можно ознакомиться на странице официальной документации Tippy.js.
`addClass`	`string/object`	Добавить дополнительный класс к кастомизированному селекту.

data-select-label #

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

    <select class="js-select">
        <option placeholder>Выберите валюту</option>
        <option data-select-label='<svg class="select-icon"><use xlink:href="#icon-usd"/></svg> Доллар'>Доллар</option>
        <option data-select-label='<svg class="select-icon"><use xlink:href="#icon-eur"/></svg> Евро'>Евро</option>
        <option data-select-label='<svg class="select-icon"><use xlink:href="#icon-rub"/></svg> Рубль'>Рубль</option>
    </select>

    <select class="js-select">
        <option placeholder>Форматирование текста</option>
        <option data-select-label='<i>Курсивом</i>'>Курсивом</option>
        <option data-select-label='<b>Жирный</b>'>Жирный</option>
        <option data-select-label='<s>Зачёркнутый</s>'>Зачёркнутый</option>
    </select>

Multiple select #

Для настройки селекта множественного выбора необходимо добавить атрибут multiple.

    <select multiple class="js-select">
        <option placeholder>Выберите фрукты</option>
        <option selected>Яблоко</option>
        <option selected>Апельсин</option>
        <option>Арбуз</option>
        <option>Виноград</option>
        <option>Сливы</option>
        <option>Мандарины</option>
        <option>Грушы</option>
    </select>

Данный тип селекта также поддерживает data-select-label.

    <select multiple class="js-select">
        <option placeholder>Форматирование текста</option>
        <option data-select-label='<i>Курсивом</i>'>Курсивом</option>
        <option data-select-label='<b>Жирный</b>'>Жирный</option>
        <option data-select-label='<s>Зачёркнутый</s>'>Зачёркнутый</option>
        <option data-select-label='<u>Подчёркнутый</u>'>Подчёркнутый</option>
        <option data-select-label='<mark>Выделенный</mark>'>Выделенный</option>
    </select>

Optgroup #

Установка #

Поддерживает группировку опций внутри селекта. Работает с типами селектов default и multiple.

    <select class="js-select">
		<optgroup label="Заголовки">
			<option data-select-label='Заголовок h1'>Заголовок h1</option>
			<option data-select-label='Заголовок h2'>Заголовок h2</option>
			<option data-select-label='Заголовок h3'>Заголовок h3</option>
		</optgroup>

		<optgroup label="Обычное форматирование">
			<option data-select-label='<i>Курсивом</i>'>Курсивом</option>
			<option data-select-label='<b>Жирный</b>'>Жирный</option>
			<option data-select-label='<s>Зачёркнутый</s>'>Зачёркнутый</option>
			<option data-select-label='<u>Подчёркнутый</u>'>Подчёркнутый</option>
			<option data-select-label='<mark>Выделенный</mark>'>Выделенный</option>
		</optgroup>
    </select>

Методы #

У групп существуют свои методы.

groupCreate() #

Создать новую группу с опциями. Метод работает с типами селектов default и multiple.

    BasicSelect.groupCreate({
        "el": "#my-select",
		"name": "Новая группа",
        "value": [
            {
                "label": "<b>Новый пункт списка</b>",
                "value": "Новый пункт списка",
                "selected": true
            },

            {
                "label": "<i>Ещё один пункт списка</i>",
                "value": "Ещё один пункт списка",
                "disabled": true
            }
        ]
    });

где в конфигурациях указывается:

Название	Тип	Описание
`el`	`object`/`string`	Оригинальный селект(`.js-select`), к которому необходимо добавить новые элементы.
`name`	`string`	Название группы.
`value`	`object`	Массив дочерних элементов группы, где `label` — это внешний вид элемента, а `value` — необходимое значение, `selected` — заранее выбрать элемент, `disabled` — заранее заблокированный элемент.

groupRemove() и groupRemoveAll() #

Исключить группы из списка. Метод работает с типами селектов default и multiple.

    BasicSelect.groupRemove({
        "el": "#my-select",
		"value": "Название группы" // если необходимо исключить из списка сразу несколько групп: ["Название группы 1", "Название группы 2"]
    });

	// или

	BasicSelect.groupRemoveAll("#my-select"); // удалить сразу все группы из селекта

конфигурации для groupRemove():

Название	Тип	Описание
`el`	`object`/`string`	Оригинальный селект(`.js-select`), из списка которого нужно исключить определённую группу.
`value`	`string`	Название группы из списка, которую необходимо исключить. которую следует исключить из списка. Если нужно исключить сразу несколько групп, то необходимо указать их названия в виде массива.

groupAdd() #

Добавить в группу новые дочерние элементы. Метод работает с типами селектов default и multiple.

    BasicSelect.groupAdd({
        "el": "#my-select",
		"name":   "Название группы",
        "value": [
            {
                "label": "<b>Новый пункт списка</b>",
                "value": "Новый пункт списка",
                "selected": true
            },

            {
                "label": "<i>Ещё один пункт списка</i>",
                "value": "Ещё один пункт списка",
                "disabled": true
            }
        ]
    });

где в конфигурациях указывается:

Название	Тип	Описание
`el`	`object`/`string`	Оригинальный селект(`.js-select`), в который нужно добавить новые элементы.
`name`	`string`	Название группы, в которую нужно добавить новые элементы.
`value`	`object`	Массив новых дочерних элементов группы, где `label` — это внешний вид элемента, а `value` — необходимое значение, `selected` — заранее выбрать новый элемент, `disabled` — заранее заблокировать элемент.

groupDisabled() и groupEnabled() #

Заблокировать или разблокировать группу из списка. Метод работает с типами селектов default и multiple.

    BasicSelect.groupDisabled({
        "el": "#my-select",	  	    // оригинальный селект(к примеру .js-select).
		"value":  "Название группы" // название группы, которую необходимо заблокировать.
    });

	// или разблокировать

	BasicSelect.groupEnabled({
        "el": "#my-select",	  	    // оригинальный селект(к примеру .js-select).
		"value":  "Название группы" // название группы, которую необходимо разблокировать.
    });

Методы #

add() #

Добавить новые элементы в список кастомизированного селекта. Метод работает с типами селектов default и multiple.

    BasicSelect.add({
        "el": "#my-select",
        "value": [
            {
                "label": "<b>Новый пункт списка</b>",
                "value": "Новый пункт списка",
                "selected": true
            },

            {
                "label": "<i>Ещё один пункт списка</i>",
                "value": "Ещё один пункт списка",
                "disabled": true
            }
        ]
    });

где в конфигурациях указывается:

Название	Тип	Описание
`el`	`object`/`string`	Оригинальный селект(`.js-select`), в который нужно добавить новые элементы.
`value`	`object`	Массив новых элементов, где `label` — это внешний вид элемента, а `value` — значение элемента, `selected` — заранее выбранный элемент, `disabled` — заранее заблокированный элемент.

choose() и chooseAll() #

Выбрать элемент или элементы из кастомизированного селекта. Метод работает с типами селектов default и multiple.

    BasicSelect.choose({
        "el": "#my-select",
        "value":  "Пункт списка" // если необходимо выбрать сразу несколько элементов из списка: ["Пункт списка", "Ещё один пункт списка"]
    });

    // или

    BasicSelect.chooseAll('#my-select') // выбрать сразу все выбранные элементы из списка

конфигурации для choose():

Название	Тип	Описание
`el`	`object`/`string`	Оригинальный селект(`.js-select`), в котором необходимо выбрать элементы.
`value`	`object`/`string`	Необходимо указать значение элемента из списка, который нужно выбрать. Если требуется выбрать сразу несколько элементов, то следует представить их в виде массива.

clear() и clearAll() #

Очистить кастомизированный селект от выбора. Методы работают с типами селектов default и multiple.

    BasicSelect.clear({
        "el": "#my-select",
        "value":  "пункт списка" // если надо очистить от несколько выбранных элементов: ["Пункт списка", "Ещё один пункт списка"]
    });

    // или

    BasicSelect.clearAll('#my-select') // очистить сразу все выбранные элементы из списка

конфигурации для clear():

Название	Тип	Описание
`el`	`object`/`string`	Оригинальный селект(`.js-select`), который необходимо очистить от выбранных элементов.
`value`	`object`/`string`	Необходимо указать значение выбранного элемента из списка, от которого необходимо очистить селектор. Если требуется удалить несколько элементов, то необходимо указать их в виде массива.

remove() и removeAll() #

Удаляет дочерние элементы из списка кастомизированного селекта. Методы работают с типами селектов default и multiple.

    BasicSelect.remove({
        "el": "#my-select",
        "value":  "пункт списка" // если надо удалить сразу несколько элементов из списка: ["Пункт списка", "Ещё один пункт списка"]
    });

    // или

    BasicSelect.removeAll('#my-select'); // удалить сразу все элементы из списка

конфигурации для remove():

Название	Тип	Описание
`el`	`object`/`string`	Оригинальный селект(`.js-select`), из которого необходимо удалить элемент.
`value`	`object`/`string`	Необходимо указать значение элемента, который требуется удалить из списка. Если нужно удалить несколько элементов, то их следует указать в виде массива.

show() и hide() #

Показать/скрыть выпадающий список кастомизированного селекта. Методы работают с типами селектов default и multiple.

    BasicSelect.show('#my-select'); // показать выпадающий список
    BasicSelect.hide('#my-select'); // скрыть выпадающий список

disabled() и enabled() #

Заблокировать или разблокировать кастомизированный селект. Методы работают с типами селектов default и multiple.

    BasicSelect.disabled('#my-select'); // заблокировать селект
    BasicSelect.enabled('#my-select'); // разблокировать селект

disabledOption() и enabledOption() #

Заблокировать или разблокировать дочерние элементы из списка кастомизированного селекта. Методы работают с типами селектов default и multiple.

    BasicSelect.disabledOption({
        "el": "#my-select",
        "value":  "пункт списка" // если надо заблокировать сразу несколько элементов из списка: ["Пункт списка", "Ещё один пункт списка"]
    });

    // или разблокировать

    BasicSelect.enabledOption({
        "el": "#my-select",
        "value":  "пункт списка" // если надо разблокировать сразу несколько элементов из списка: ["Пункт списка", "Ещё один пункт списка"]
    });

destroy() #

Уничтожает экземпляр кастомизированного селекта и возвращает оригинал в первоначальный вид. Метод работает с селектами default и multiple.

    BasicSelect.destroy("#my-select");

Экземпляр #

У каждого инициализированного элемента есть свой экземпляр.

	const myCustomSelect = document.querySelector(".my-select");

	console.log(myCustomSelect.BasicSelect); // пример экземпляра

В настоящее время экземпляр поддерживает все методы.

Прослушивание событий #

Можно прослушать события элемента и получить необходимые параметры.

select:choice #

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

Параметры:

Название	Тип	Описание
`event.detail.el`	`object`	Оригинальный селект(`.js-select`).
`event.detail.index`	`number`	`index` селекта.
`event.detail.select`	`object`	Кастомизированный селект.
`event.detail.target`	`object`	Пункт из списка, с которым связано главное событие.
`event.detail.selected`	`boolean`	Указывает статус выбранного пункта из списка.
`event.detail.value`	`string` или `object`	Значение селекта. `string` — default select, `object` — multiple select.

    document.querySelector('#my-select').addEventListener('select:choice', function() {

        console.log(event.detail); // параметры

    }, false);

select:clear #

Срабатывает при очистке кастомизированного селекта от выбора.

Параметры:

Название	Тип	Описание
`event.detail.el`	`object`	Оригинальный селект(`.js-select`).
`event.detail.index`	`number`	`index` селекта.
`event.detail.select`	`object`	Кастомизированный селект.
`event.detail.previous`	`object`	Предыдущий выбранный элемент из списка.
`event.detail.selected`	`boolean`	Указывает статус выбранного элемента.
`event.detail.value`	`string`	Значение селекта.

    document.querySelector('#my-select').addEventListener('select:clear', function() {

        console.log(event.detail); // параметры

    }, false);

select:visibility #

Срабатывает при показе или скрытия выпадающего списка кастомизированного селекта.

Параметры:

Название	Тип	Описание
`event.detail.el`	`object`	Оригинальный селект(`.js-select`).
`event.detail.index`	`number`	`index` селекта.
`event.detail.select`	`object`	Кастомизированный селект.
`event.detail.dropdown`	`object`	Выпадающий список селекта.
`event.detail.tippy`	`object`	Параметры tippy экземпляра селекта.
`event.detail.show`	`boolean`	Указывает статус видимости списка селекта.

    document.querySelector('#my-select').addEventListener('select:visibility', function() {

        console.log(event.detail); // параметры

    }, false);