# Combobox

Async-пошук без локальної фільтрації — компонент показує рівно те, що дійшло з сервера.


Відмінність від Select принципова: Select фільтрує свій статичний список
локально, Combobox — НІ. Панель показує рівно те, що споживач поклав в
`options`. Подвійна фільтрація (тут + сервером) ховала б валідні матчі,
які сервер знайшов за іншим полем.

## Приклад


Example (app/demos/combobox/ComboboxAsync.vue):

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

// Фейковий async-пошук: споживач дебаунить сам, компонент лише емітує search.
const allCities = ['Київ', 'Львів', 'Одеса', 'Харків', 'Дніпро', 'Вінниця', 'Полтава', 'Чернігів']

const options = ref<ComboboxOption[]>([])
const loading = ref(false)
const selected = ref<string | null>(null)
let timer: ReturnType<typeof setTimeout> | undefined

function onSearch(query: string) {
  if (timer) clearTimeout(timer)
  loading.value = true
  timer = setTimeout(() => {
    const needle = query.toLowerCase()
    options.value = allCities
      .filter((city) => city.toLowerCase().includes(needle))
      .map((city) => ({ value: city, label: city }))
    loading.value = false
  }, 400)
}
</script>

<template>
  <div class="max-w-sm">
    <UiCombobox
      v-model="selected"
      :options="options"
      :loading="loading"
      label="Місто"
      placeholder="Почніть набирати…"
      @search="onSearch"
    />
    <p class="mt-2 text-xs text-muted">Обрано: {{ selected || '—' }}</p>
  </div>
</template>
```


## API

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

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

Вибір з ВЕЛИКИХ або віддалених наборів: користувачі, групи, моделі,
міста. `minChars` береже сервер від пошуку по одній букві: коротший запит
лише ховає панель, а набраний текст лишається в полі.

## Значення поза поточними результатами

`options` тут — відповідь на ОСТАННІЙ пошук, а не довідник. Тож назву
обраного компонент запам'ятовує сам: новий пошук, що вже не повертає
обраний пункт, не стирає поле і не ховає хрестик.

Єдиний випадок, коли назву взяти нізвідки, — форма редагування до першого
пошуку: значення є, а `options` ще порожні. Для нього є `selected-label`:

```vue
<UiCombobox
  v-model="cityId"
  :options="results"
  :selected-label="order.cityName"
  @search="searchCities"
/>
```

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

Для статичного списку на 5–50 пунктів потрібен Select: локальна
фільтрація миттєва й не коштує запитів.

Для мультивибору є MultiSelect.

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

До 768px поле стає кнопкою, а пошук і результати відкриваються нижнім
sheet'ом фіксованої висоти, як у [Select](https://ui.tatet.net/docs/components/select#на-мобільному).
Фокус одразу в полі пошуку — це автокомпліт, набір тексту тут єдиний спосіб
вибору.

Запит у sheet'і окремий від тексту поля: під фоном і далі видно назву
обраного. Відкриття порожнього sheet'а віддає `search('')`, якщо попередній
запит був непорожнім (і `minChars` дорівнює 0), — інакше список лишився б
відфільтрованим запитом, якого в пошуку вже не видно. Запит коротший за
`minChars` не показує ні списку, ні «нічого не знайдено». Вимикається через
`:mobile-sheet="false"`.

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

Той самий ARIA-комбобокс, що в Select: `role="combobox"`,
`aria-autocomplete="list"`, панель — `listbox`, пункти — `option` з
`aria-selected`. `Escape` закриває панель і не «протікає» в модалку
навколо. Escape, Tab і клік поза полем скасовують недописаний запит —
у полі знову назва обраного.

Клік у поле лише відкриває панель: клік, яким переставляють каретку, не
закриває її разом із запитом. Закрити мишею — шевроном або кліком поза
полем. Атрибути, що не є props (`aria-label`, `data-*`), ідуть на саме поле.

Стан завантаження замінює шеврон спінером і показує «Завантаження…» в
панелі — користувач розуміє, що пошук живий, а не зламався.


## Event descriptions

- `update:modelValue`: Обране значення або `null`, якщо вибір скинуто.
- `search`: Введений текст. Споживач дебаунить і фетчить сам.


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