Multiselect

Поместите multiselect в Field, чтобы у него были подпись, подсказка и ошибка. Без Field задайте aria-label, иначе у поля не будет имени вовсе.

Анатомия

Варианты

• field (по умолчанию): поле формы с чипами. Имя дайте через Field или aria-label.
• filter: компактная кнопка для панели фильтров. Пока ничего не выбрано, на ней написано «Status», потом «Status (2)», и у неё появляется заливка. Выбор живёт в меню, чипов нет. filter-label обязателен: это и видимый текст, и доступное имя. Не помещайте фильтр в Field.

Поиск

searchable добавляет текстовое поле, которое фильтрует меню по мере ввода, как в Combobox. Нужен для длинных списков. Загрузчик loadOptions включает его сам. Вариант filter поиска не поддерживает.

Размеры

Когда в поле есть чипы, отступ слева сокращается до space-4, чтобы чипы выровнялись по краю. Чипы переносятся, и поле растёт; max-rows ограничивает его примерно этим числом строк, остальное прокручивается.

Состояния

При наведении поле не меняется. При фокусе с клавиатуры его рамка меняет цвет и становится толще; отдельной рамки фокуса снаружи нет. Когда фокус на чипе, рамку фокуса показывает чип. Вариант filter при наведении тонируется и при фокусе показывает рамку фокуса.

• disabled: на поле нельзя перейти, меню не открывается, значения не отправляются. Чипы удалить нельзя.
• readonly: чипы видны и отправляются. На поле можно перейти, но меню не открывается, чипы не удаляются, кнопка «очистить всё» и шеврон скрыты.
• Ошибка: задайте error на Field. Сообщение появится ниже, а рамка станет красной, даже в фокусе. Вариант filter красным не становится.

Ограничение выбора

max ограничивает число выбранных пунктов. Когда предел достигнут, остальные пункты отключаются, а меню пишет «You can choose up to 2.» Выбранные пункты по-прежнему можно убрать.

Пункты и данные

• Пункты пишутся дочерними <option>, группы — через <optgroup>. selected задаёт начальный выбор.
• data-description добавляет в меню короткую вторую строку; на чипе видно только название.
• Пункты можно передать и через свойство options или загрузчик loadOptions, как в Combobox. С загрузчиком строка поиска есть всегда.
• creatable добавляет строку Create "…", когда поиск ничего не нашёл; её выбор добавляет новый чип. Работает по правилам Combobox и останавливается на max.

Когда использовать

• Multiselect нужен, когда можно выбрать несколько пунктов из списка, который слишком длинный, чтобы показать его целиком.
• Для короткого набора, который помещается на экране, берите Checkbox group. Она проще и показывает все пункты.
• Если выбирают ровно один пункт, нужен Select или Combobox.

Текст

• Подпись: назовите, что вы спрашиваете, с заглавной буквы только в первом слове, без двоеточия.
• Placeholder: «Choose…». Он пропадает, когда что-то выбрано, поэтому не пишите в нём ничего нужного.
• Пункты: каждый в одну короткую строку, в порядке, который легко угадать. Ставьте первым слово, по которому пункты различаются. Не начинайте их с иконки или эмодзи.
• Предел: если задан max, скажите об этом в подсказке: «Choose up to 3».
• Ошибка: скажите, как её исправить, словами подписи: «Choose at least one topic».

Подробнее в Errors.

Можно / нельзя

Связанные

• Field: подпись, подсказка и ошибка вокруг multiselect.
• Checkbox group: короткий набор, всё на виду.
• Select: один пункт из короткого списка; у него такой же вариант filter.
• Combobox: один пункт из длинного списка, с той же фильтрацией.
• Tag: чип, из которого собран multiselect.
• Select family: как они соотносятся.

API

Атрибуты

Свойства

Слоты

События

change срабатывает, когда человек отмечает или снимает пункт, удаляет чип, очищает всё или создаёт пункт. Оно не срабатывает, когда вы задаёте value из кода. Новое значение читайте из value.

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

CSS

• ::part(field): поле или кнопка в варианте filter.
• ::part(listbox): меню.

Токены

Поле, меню, пункты, ошибка и фокус используют токены Select; чипы — серые Tag; кнопка «очистить всё» такая же, как кнопка очистки в Combobox. Отличаются только эти:

Доступность

Уже встроено:

• Скринридер объявляет combobox со списком множественного выбора. Про каждый пункт сказано, выбран он или нет, а скрытое статусное сообщение после каждого изменения называет итог, например «2 selected.».
• Одна остановка Tab. Чипы не остановки Tab; к ним переходят стрелками.
• Кнопка удаления на каждом чипе называется «Remove» плюс пункт, например «Remove Red».
• Кнопка «очистить всё» называется «Clear all». Это не остановка Tab; с клавиатуры чипы удаляют по одному.
• Меню не закрывается, пока человек выбирает, и Esc никогда не меняет выбор.
• При увеличении меню остаётся на экране. Каждая строка не ниже 32px.

Ваша часть:

• Дайте каждому multiselect имя: подпись Field, aria-label или filter-label.
• Если есть предел, задайте max и назовите его в подсказке.
• Пишите ошибки по правилам из раздела «Текст».

На чипе: Left / Right переходят между чипами, Right после последнего возвращает в поле, Home ведёт к первому чипу, End возвращает в поле, а Delete или Backspace удаляют чип.

Пределы контраста

• Рамка поля: 1.33:1 в светлой теме и 2.00:1 в тёмной, ниже минимума 3:1; 4.22:1 в высококонтрастной. Всегда показывайте подпись.
• Placeholder: 3.26:1 в светлой теме, ниже минимума 4.5:1 для текста. Не пишите в нём ничего нужного.