Dropdown

<sf-dropdown> — поле выбора одного или нескольких значений из раскрывающегося списка с поиском. Берите его, когда вариантов больше, чем удобно показать радиокнопками или флажками, или когда значения нужно показать тегами.

Пример

HTML

<div class="flex flex-col gap-2">
  <sf-dropdown id="view-picker" name="view" label="Представление" placeholder="Выберите представление" search-placeholder="Найти">
    <sf-list-item value="all" text="Все элементы"></sf-list-item>
    <sf-list-item value="active" text="Активные"></sf-list-item>
    <sf-list-item value="archived" text="В архиве"></sf-list-item>
  </sf-dropdown>
  <output id="view-picker-output" class="color-on-surface-variant" aria-live="polite">Представление не выбрано</output>
</div>

JavaScript

// `change` names the picked item; the element itself answers what is selected
// now: `value` is the machine value, `triggerText` the label the field shows.
// Only the dropdown's own event is read: a listener on an ancestor would
// also hear native events from fields inside it.
const initializeViewPicker = async () => {
  const picker = document.getElementById('view-picker');
  const output = document.getElementById('view-picker-output');
  if (!picker || !output || picker.dataset.exampleReady === 'true') return;
  picker.dataset.exampleReady = 'true';

  await customElements.whenDefined('sf-dropdown');
  picker.addEventListener('change', (event) => {
    if (event.target !== picker) return;
    output.value = picker.value
      ? `Представление: ${picker.triggerText} (${picker.value})`
      : 'Представление не выбрано';
  });
};

initializeViewPicker();

Применение

Имя, подпись и пояснение

name — машинное имя отправляемого значения, label — видимая подпись поля; они не дублируют друг друга. placeholder приглашает к выбору, но не заменяет подпись. search-placeholder относится только к полю поиска внутри раскрытого списка; без атрибута в нём слово на языке страницы — «Поиск», по-английски «Search».

aria-label на <sf-dropdown> заменяет видимую подпись в доступном имени. Задавайте его, только если адаптеру нужно отдельное имя, и с тем же локализованным смыслом, что у label. В компактной панели инструментов подпись можно скрыть только визуально — это решается композицией панели, а не другим вызовом Dropdown.

Группы в списке

Пункт может сказать, откуда он: поле group в данных options или атрибут group у sf-list-item. Идущие подряд пункты с одинаковым group рисуются под одним заголовком, поэтому длинный список читается кусками, а название места не повторяется в каждой строке.

HTML

<div class="sf-dropdown sf-dropdown--size-1 sf-dropdown--outlined sf-dropdown--text flex flex-col" multiple value="code,title">
  <span class="sf-dropdown-label"><span class="sf-dropdown-text">Поля карточки</span></span>
  <div class="sf-dropdown-field cursor-pointer items-cross-center transition flex relative"><input class="sf-dropdown-hidden-input" type="hidden" name="fields"><input type="text" placeholder="Выберите поля"><button type="button" class="sf-icon-button sf-icon-button--icon sf-icon-button--link sf-icon-button--size-1 absolute" aria-label="Открыть: Поля карточки"><i class="sf-icon" aria-hidden="true">keyboard_arrow_down</i></button></div>
  <div class="sf-list flex flex-col"><label class="sf-input sf-input--size-1 sf-input--filled flex flex-col"><span class="sf-input-field items-cross-center transition flex"><input type="text" aria-label="Поиск по списку" placeholder="Начните вводить"><i class="sf-icon sf-icon-hint" aria-hidden="true">search</i></span></label><div class="sf-list-container-wrap"><div class="sf-list-container flex flex-col">
    <div class="sf-list-heading" role="presentation"><span class="sf-list-heading-container">В этой области</span></div>
    <div class="sf-list-item sf-list-item--checkbox sf-list-item--size-1 cursor-pointer selected" role="option" tabindex="-1" data-value="code" aria-selected="true"><div class="sf-list-item-wrap flex flex-1 flex flex-row flex-nowrap items-center gap-2"><label class="sf-checkbox sf-checkbox--size-1 flex" aria-hidden="true"><span class="sf-checkbox-box flex"><input type="checkbox" tabindex="-1" checked><span class="sf-icon" aria-hidden="true"></span></span></label><div class="sf-list-item-container">Код решения</div></div></div>
    <div class="sf-list-item sf-list-item--checkbox sf-list-item--size-1 cursor-pointer selected" role="option" tabindex="-1" data-value="title" aria-selected="true"><div class="sf-list-item-wrap flex flex-1 flex flex-row flex-nowrap items-center gap-2"><label class="sf-checkbox sf-checkbox--size-1 flex" aria-hidden="true"><span class="sf-checkbox-box flex"><input type="checkbox" tabindex="-1" checked><span class="sf-icon" aria-hidden="true"></span></span></label><div class="sf-list-item-container">Название</div></div></div>
    <div class="sf-list-heading" role="presentation"><span class="sf-list-heading-container">Не размещённые</span></div>
    <div class="sf-list-item sf-list-item--checkbox sf-list-item--size-1 cursor-pointer" role="option" tabindex="-1" data-value="scripts" aria-selected="false"><div class="sf-list-item-wrap flex flex-1 flex flex-row flex-nowrap items-center gap-2"><label class="sf-checkbox sf-checkbox--size-1 flex" aria-hidden="true"><span class="sf-checkbox-box flex"><input type="checkbox" tabindex="-1"><span class="sf-icon" aria-hidden="true"></span></span></label><div class="sf-list-item-container">Скрипты в head</div></div></div>
    <div class="sf-list-heading" role="presentation"><span class="sf-list-heading-container">Работа</span></div>
    <div class="sf-list-item sf-list-item--checkbox sf-list-item--size-1 cursor-pointer" role="option" tabindex="-1" data-value="author" aria-selected="false"><div class="sf-list-item-wrap flex flex-1 flex flex-row flex-nowrap items-center gap-2"><label class="sf-checkbox sf-checkbox--size-1 flex" aria-hidden="true"><span class="sf-checkbox-box flex"><input type="checkbox" tabindex="-1"><span class="sf-icon" aria-hidden="true"></span></span></label><div class="sf-list-item-container">Автор</div></div></div>
    <div class="sf-list-item sf-list-item--checkbox sf-list-item--size-1 cursor-pointer" role="option" tabindex="-1" data-value="progress" aria-selected="false"><div class="sf-list-item-wrap flex flex-1 flex flex-row flex-nowrap items-center gap-2"><label class="sf-checkbox sf-checkbox--size-1 flex" aria-hidden="true"><span class="sf-checkbox-box flex"><input type="checkbox" tabindex="-1"><span class="sf-icon" aria-hidden="true"></span></span></label><div class="sf-list-item-container">Прогресс, %</div></div></div>
  </div></div></div>
</div>

Сетка пунктов

layout="grid" раскладывает пункты по нескольку в ряд, columns задаёт сколько. Сетка выше нескольких рядов прокручивается; её высоту задаёт токен --sf-dropdown--grid-height. Ячейка сетки высотой с поле того же размера, что и список, а сетка за собственным триггером шириной ровно в свои колонки. В сетке пункт показывает свою картинку, а подпись остаётся именем для поиска и подсказкой при наведении. Так удобно выбирать из сотни значков: колонкой их не долистать.

Свой триггер

Собственный триггер Dropdown — поле: рамка, текст выбранного, шеврон. Там, где список нужен за другим управляющим элементом — за «+» в шапке группы, за кнопкой со значком, — передайте его в slot="trigger". Компонент отдаёт такому триггеру только нажатие, которое открывает список; как триггер выглядит, решает тот, кто его передал. Список в этом случае берёт свою ширину, а не ширину кнопки.

HTML

<div class="sf-dropdown sf-dropdown--size-1 sf-dropdown--outlined sf-dropdown--text flex flex-col" value="payments">
  <div class="sf-dropdown-trigger flex items-cross-center"><button type="button" class="sf-icon-button sf-icon-button--icon sf-icon-button--link sf-icon-button--on-surface sf-icon-button--size-1" aria-label="Значок раздела"><i class="sf-icon" aria-hidden="true">payments</i></button></div>
  <div class="sf-list sf-list--free-width flex flex-col"><label class="sf-input sf-input--size-1 sf-input--filled flex flex-col"><span class="sf-input-field items-cross-center transition flex"><input type="text" aria-label="Поиск по списку" placeholder="Начните вводить"><i class="sf-icon sf-icon-hint" aria-hidden="true">search</i></span></label><div class="sf-list-container-wrap"><div class="sf-list-container sf-list-container--grid flex flex-col">
    <div class="sf-list-item sf-list-item--icon sf-list-item--size-1 cursor-pointer" role="option" tabindex="-1" data-value="folder" aria-selected="false" title="folder"><div class="sf-list-item-wrap flex flex-1 flex flex-row flex-nowrap items-center gap-2"><i class="sf-icon" aria-hidden="true">folder</i><div class="sf-list-item-container">folder</div></div></div>
    <div class="sf-list-item sf-list-item--icon sf-list-item--size-1 cursor-pointer" role="option" tabindex="-1" data-value="person" aria-selected="false" title="person"><div class="sf-list-item-wrap flex flex-1 flex flex-row flex-nowrap items-center gap-2"><i class="sf-icon" aria-hidden="true">person</i><div class="sf-list-item-container">person</div></div></div>
    <div class="sf-list-item sf-list-item--icon sf-list-item--size-1 cursor-pointer selected" role="option" tabindex="-1" data-value="payments" aria-selected="true" title="payments"><div class="sf-list-item-wrap flex flex-1 flex flex-row flex-nowrap items-center gap-2"><i class="sf-icon" aria-hidden="true">payments</i><div class="sf-list-item-container">payments</div></div></div>
    <div class="sf-list-item sf-list-item--icon sf-list-item--size-1 cursor-pointer" role="option" tabindex="-1" data-value="schedule" aria-selected="false" title="schedule"><div class="sf-list-item-wrap flex flex-1 flex flex-row flex-nowrap items-center gap-2"><i class="sf-icon" aria-hidden="true">schedule</i><div class="sf-list-item-container">schedule</div></div></div>
    <div class="sf-list-item sf-list-item--icon sf-list-item--size-1 cursor-pointer" role="option" tabindex="-1" data-value="mail" aria-selected="false" title="mail"><div class="sf-list-item-wrap flex flex-1 flex flex-row flex-nowrap items-center gap-2"><i class="sf-icon" aria-hidden="true">mail</i><div class="sf-list-item-container">mail</div></div></div>
    <div class="sf-list-item sf-list-item--icon sf-list-item--size-1 cursor-pointer" role="option" tabindex="-1" data-value="settings" aria-selected="false" title="settings"><div class="sf-list-item-wrap flex flex-1 flex flex-row flex-nowrap items-center gap-2"><i class="sf-icon" aria-hidden="true">settings</i><div class="sf-list-item-container">settings</div></div></div>
    <div class="sf-list-item sf-list-item--icon sf-list-item--size-1 cursor-pointer" role="option" tabindex="-1" data-value="palette" aria-selected="false" title="palette"><div class="sf-list-item-wrap flex flex-1 flex flex-row flex-nowrap items-center gap-2"><i class="sf-icon" aria-hidden="true">palette</i><div class="sf-list-item-container">palette</div></div></div>
    <div class="sf-list-item sf-list-item--icon sf-list-item--size-1 cursor-pointer" role="option" tabindex="-1" data-value="code" aria-selected="false" title="code"><div class="sf-list-item-wrap flex flex-1 flex flex-row flex-nowrap items-center gap-2"><i class="sf-icon" aria-hidden="true">code</i><div class="sf-list-item-container">code</div></div></div>
  </div></div></div>
</div>

Значение и событие `change`

Свойство value возвращает выбранное машинное значение строкой. При multiple значения перечислены через запятую, без выбора это пустая строка. Присваивание value принимает строку или массив строк и выбирает пункты с этими значениями. Кнопки очистки нет: из кода присвойте value = ''; событие change при этом не приходит. Присвоенный массив options перерисовывает список и сохраняет выбранное значение, если такой вариант в нём есть.

Выбор пункта и удаление тега отправляют всплывающее событие change. Его event.detail:

Поле	Содержимое
`value`	значение нажатого пункта; при удалении тега — пустая строка
`label`	подпись нажатого пункта; при удалении тега — пустая строка
`values`	массив всех выбранных значений после изменения
`item`	данные нажатого пункта; при удалении тега — `null`
`root`	элемент `<sf-dropdown>`
`multiple`	`true`, если разрешён выбор нескольких значений

Полное значение после изменения дают event.detail.values и event.target.value. Повторный выбор уже выбранного пункта change не отправляет, а при multiple снимает выбор пункта и отправляет change.

Событие change на элементе отправляет только сам компонент: нативный change своего поля поиска он останавливает. Слушатель на предке, например на форме, слышит и change других полей, поэтому проверяет event.target.

Свойство selectedOptions возвращает данные выбранных пунктов — те же, что приходят в event.detail.item. Свойство triggerText возвращает подписи выбранных пунктов через запятую, как их показывает поле; при mode="tag" оно пустое, потому что выбранное показывают теги.

JavaScript

const view = document.querySelector('sf-dropdown[name="view"]');
view.addEventListener('change', (event) => {
  applyView(event.detail.values);
});
view.value = 'archived';

Доступность

Каждому Dropdown нужно доступное имя: видимый label или aria-label. Один placeholder имени не даёт.
Триггер — одна остановка Tab. Стрелки открывают список и перемещают по пунктам, Home и End — к первому и последнему, Enter и Space выбирают, Escape закрывает список и возвращает фокус на триггер.
Поле поиска в списке сохраняет обычное поведение Home и End при редактировании текста.
Свой триггер в slot="trigger" должен быть кнопкой с доступным именем: у кнопки со значком — aria-label.

Справочник API

Раздел собран из манифеста компонента выпуска ui-106d5901f8c3 и обновляется вместе с выпуском. Чтобы исправить описание, исправьте манифест.

Каждому атрибуту соответствует свойство элемента с тем же именем в camelCase: search-placeholder — searchPlaceholder. Свойство атрибута template называется templateName.


Тег	`<sf-dropdown>`
Назначение	Доступный элемент одиночного или множественного выбора с поиском по вариантам и необязательным выводом в портал.
Контракт	`smart.dropdown`, версия `1.2.0`
Поставка	выпуск Framework `ui-106d5901f8c3`
Жизненный цикл	экспериментальный: API может меняться между выпусками
Готовность	описан: манифест и сценарий есть, продуктовой приёмки нет
Заготовка до прихода кода	нет: атрибут `data-sf-skeleton` не пишется; своего скелетона при загрузке данных нет (Заготовка до прихода кода)

Атрибуты

appearance — string, по умолчанию outlined, значения: filled, outlined. Вид выпадающего списка: поле с заливкой или с контуром.
aria-label — string, по умолчанию пусто.
columns — string, по умолчанию 6. Сколько вариантов помещается в строку в раскладке-сетке. В списке игнорируется.
disabled — boolean, по умолчанию false.
label — string, по умолчанию пусто.
layout — string, по умолчанию list, значения: list, grid. Раскладка вариантов. В списке — один вариант в строке; в сетке — несколько в строке, и только так можно просмотреть сотню символов: их столбец никто не прокручивает до конца. В сетке вариант показывает изображение, а текст сохраняется как имя для поиска и подсказки при наведении.
mode — string, по умолчанию select, значения: tag, select.
multiple — boolean, по умолчанию false. Разрешает несколько значений с сохранением порядка выбора при сериализации. В режиме тегов множественный выбор включён по умолчанию.
name — string, по умолчанию пусто. Имя нативного поля формы для выбранного машинного значения.
options — array, по умолчанию []. Варианты, переданные данными вместо дочерних sf-list-item: [{text, value, type?, size?, icon?, selected?, disabled?, colorClass?, avatarImageUrl?, avatarTitle?, ariaLabel?, group?}]. Строка или число используется и как подпись, и как значение. Родитель, отрисовывающий этот выпадающий список из шаблона, передаёт варианты так, потому что захват дочерних элементов означает их удаление, и родитель уже не сможет вернуть изменённый список. Идущие подряд варианты с одинаковым group выводятся под одним заголовком, чтобы длинный список показывал, откуда взят каждый его фрагмент, а не повторял это в каждой строке.
placeholder — string, по умолчанию пусто.
portal — boolean, по умолчанию true. Привязывает всплывающее окно с помощью общего позиционирования Framework (SF.Position): нативный верхний слой, переворот, сдвиг и высота, ограниченная окном просмотра. Включено по умолчанию; portal="false" оставляет список в потоке.
required — boolean, по умолчанию false.
search — boolean, по умолчанию true.
search-placeholder — string, по умолчанию пусто. Пусто — текст на языке страницы (по-английски «Search»).
size — string, по умолчанию 1, значения: 1/2, 1, 2.
template — string, по умолчанию default.
value — string, по умолчанию пусто. Выбранное машинное значение или список значений через запятую при множественном выборе.

Прежние имена:

Имя	Прежнее имя	Состояние	Убирается после
`appearance`	`type`	работает, отмечается в `SF.deprecations`	2026-12-01
`size="1/2"`	`size="1/3"`	работает, отмечается в `SF.deprecations`	2026-12-01
`size="2"`	`size="3"`	работает, отмечается в `SF.deprecations`	2026-12-01

Методы

openDropdown() — возвращает object. Открывает список вариантов, если элемент управления не отключён и ещё не открыт. Возвращает элемент.
closeDropdown() — возвращает object. Закрывает список вариантов и очищает текст поиска. Возвращает элемент.
toggleDropdown() — возвращает object. Закрывает список, если он открыт, иначе открывает. Возвращает элемент.

События

Все события приходят на сам элемент и всплывают. Общие события базового элемента перечислены в главе Жизненный цикл → Этапы.

change — detail: { value: string, label?: string, values: array, item?: any, root?: any, multiple: boolean }. Выбор изменился; событие отправляется на элементе. Имя для привязки.
sf-dropdown:change — устаревший псевдоним события change: приходит с тем же detail, подписывайтесь на change.

Доступность

Роль: кнопка (button) со всплывающим списком (listbox).
Доступное имя: обязательно.
Клавиши: Tab, ArrowDown, ArrowUp, Home, End, Enter, Space, Escape.
Фокус: Переключатель — основная остановка Tab. Клавиши со стрелками открывают список и перемещают по доступным вариантам; Home и End перемещают в пределах списка; Enter или Space выбирают; Escape закрывает список и возвращает фокус на переключатель; Tab закрывает список и продолжает нативный обход. Поле поиска сохраняет нативное поведение Home и End при редактировании текста.

Минимальная разметка

HTML

<sf-dropdown label="Статус" name="status" placeholder="Выберите статус"><sf-list-item value="open" text="Открыт"></sf-list-item><sf-list-item value="done" text="Готов"></sf-list-item></sf-dropdown>

Источник

simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/smart/dropdown
simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/rule/rule.json#name=cl-dropdown

См. также

Context Menu — меню действий у элемента.
List Item — пункт списка вариантов.

Навигация

Главное

Документация

Содержание

Пример

Применение

Имя, подпись и пояснение

Группы в списке

Сетка пунктов

Свой триггер

Значение и событие `change`

Доступность

Справочник API

Атрибуты

Методы

События

Доступность

Минимальная разметка

Источник

См. также

Настройки

Dropdown

Пример

Применение

Имя, подпись и пояснение

Группы в списке

Сетка пунктов

Свой триггер

Значение и событие change

Доступность

Справочник API

Атрибуты

Методы

События

Доступность

Минимальная разметка

Источник

См. также

Поиск по документации

Значение и событие `change`