# MultiSelect

Мультивибір із чекбоксами, пошуком, діями «вибрати все / зняти все» та лічильником у тригері.


Мультивибір збирає найкраще з двох джерел: поведінку (пошук, «вибрати все»,
згортання вибору в «+N») успадковано з продуктової реалізації,
позиціонування й ARIA-listbox — з канонічного UiSelect.

## Приклад


Example (app/demos/multi-select/MultiSelectBasic.vue):

```vue
<script setup lang="ts">
import { ref } from 'vue'
import UiMultiSelect from '~/components/ui/UiMultiSelect.vue'
import type { MultiSelectOption } from '~/components/ui/UiMultiSelect.vue'

const options: MultiSelectOption[] = [
  { value: 'admin', label: 'Адміністратор' },
  { value: 'editor', label: 'Редактор' },
  { value: 'smm', label: 'SMM' },
  { value: 'viewer', label: 'Спостерігач' },
  { value: 'billing', label: 'Білінг' },
  { value: 'api', label: 'API-доступ' },
]

const selected = ref<string[]>(['editor'])
</script>

<template>
  <div class="max-w-md">
    <UiMultiSelect v-model="selected" :options="options" label="Ролі користувача" />
    <p class="mt-2 text-xs text-muted">Обрано: {{ selected.join(', ') || '—' }}</p>
  </div>
</template>
```


## API

[Props, events, slots, exposed API (JSON)](https://ui.tatet.net/api/component-meta/UiMultiSelect)

## Коли використовувати

Коли користувач обирає ДЕКІЛЬКА значень із відомого набору: ролі, теги,
фільтри за статусами. Лічильник у тригері показує масштаб вибору, коли
підписи вже не вміщаються.

## Коли НЕ використовувати

Для одного значення потрібен Select — два контроли з однаковим виглядом,
але різною семантикою, плутають.

Для 2–3 взаємновиключних варіантів беріть чекбокси просто в формі: вони
показують усі варіанти одразу, без кліку.

## На мобільному

До 768px список відкривається нижнім sheet'ом, як у [Select](https://ui.tatet.net/docs/components/select#на-мобільному):
рядки по 48px із чекбоксом 20px, «Вибрати все» і «Зняти все» — текстом, а не
значками (на дотику підказка `title` не з'являється), внизу — «Готово».

Пункти перемикаються одразу, як і у випадайці, тож «Готово» лише закриває:
окремого «Застосувати» немає, і закриття свайпом нічого не губить. Пошук —
від 11 пунктів і без автофокуса. Вимикається через `:mobile-sheet="false"`.

## Доступність

Тригер — `aria-haspopup="listbox"` з `aria-expanded`; панель —
`role="listbox"` з `aria-multiselectable="true"`, пункти — `role="option"`
з `aria-selected`. Стрілки й Enter працюють по відфільтрованому списку,
`Escape` закриває панель і повертає фокус на тригер, не «протікаючи» в
модалку навколо (`stopPropagation`).

Панель закривається, щойно фокус іде за межі тригера й панелі — Tab до
наступного поля не лишає її висіти над ним. Панель телепортована в кінець
`<body>`, тож на її краях Tab повертає фокус на тригер: Shift+Tab із пошуку
зупиняється на тригері, а Tab з останньої кнопки йде далі вже від тригера —
до наступного поля форми, а не за межі сторінки.

`required` дає зірочку, `aria-required` на тригері й нативну перевірку
форми. Приховані `<input type="hidden">` у валідації участі не беруть, тож
обов'язковість несе невидимий проксі-інпут під тригером — там браузер і
покаже свою підказку.

Помилка вмикається наявністю тексту, а не прапорцем: `aria-invalid` і
`aria-describedby` (>error-id) ставляться лише коли є що сказати.


## Event descriptions

- `update:modelValue`: Масив обраних значень у порядку, заданому в `options`.


[Source files, dependencies and ZIP](https://ui.tatet.net/registry/components/multi-select.json)
