Как спроектировать автокомплит (typeahead)
На этой странице
Автокомплит — поле ввода, которое по мере набора показывает подсказки: поиск товаров, городов, пользователей. Это классическая задача на UI-компонент: важны API компонента, debounce запросов, отмена устаревших ответов (race condition), кеш результатов, навигация с клавиатуры и доступность по паттерну WAI-ARIA combobox, а также поведение на медленной сети и при ошибках.
Вопрос
Как спроектировать компонент автокомплита? Как избежать лишних запросов и гонок ответов, кешировать результаты и сделать компонент доступным?
R — требования
- подсказки по мере ввода, выбор мышью и с клавиатуры;
- источник — серверный API (большой объем данных) или локальный список;
- подсветка совпадения, до 10 вариантов, состояния «загрузка», «ничего не найдено», «ошибка»;
- нефункциональные: быстро (< 100 мс на ввод), не перегружать сервер, доступность, мобильные, переиспользуемость в разных местах.
A — архитектура
<Autocomplete>
├─ <input role="combobox"> ввод, клавиатура
├─ <Listbox role="listbox"> список вариантов (порталом поверх контента)
│ └─ <Option role="option"> × N
└─ controller (хук useAutocomplete)
├─ debounce ввода
├─ запрос через fetcher (+ AbortController)
├─ кеш: Map<query, results>
└─ состояние: query, results, activeIndex, isOpen, statusЛогику выносят в headless-хук, а разметку делает компонент — так поведение можно переиспользовать с другим UI.
D — модель данных
type Option<T> = { id: string; label: string; data: T };
type AutocompleteState<T> = {
query: string;
results: Option<T>[];
activeIndex: number; // -1 — ничего не выделено
isOpen: boolean;
status: "idle" | "loading" | "success" | "error";
};
const cache = new Map<string, Option<unknown>[]>(); // ключ — нормализованный запросI — интерфейс
API компонента:
<Autocomplete<City>
fetchOptions={(query, signal) => api.searchCities(query, { signal })}
onSelect={(city) => setCity(city)}
minChars={2}
debounceMs={250}
renderOption={(option, { isActive, query }) => <Highlight text={option.label} query={query} />}
placeholder="Город"
label="Город доставки"
/>API сервера:
GET /api/search/cities?q=моск&limit=10
→ { "items": [{ "id": "msk", "label": "Москва", "region": "..." }] }O — оптимизации
Сеть и гонки:
useEffect(() => {
if (query.length < minChars) return;
const key = query.trim().toLowerCase();
if (cache.has(key)) return setResults(cache.get(key)!);
const controller = new AbortController();
const timer = setTimeout(async () => {
setStatus("loading");
try {
const items = await fetchOptions(key, controller.signal);
cache.set(key, items);
setResults(items);
setStatus("success");
} catch (e) {
if ((e as Error).name !== "AbortError") setStatus("error");
}
}, debounceMs);
return () => { clearTimeout(timer); controller.abort(); }; // новый ввод отменяет старый запрос
}, [query]);- debounce 200–300 мс сокращает запросы в разы;
AbortControllerили проверка «ответ для текущего query?» — ответ на «мо» не перезапишет «москва»;- кеш в памяти с ограничением размера (LRU) и TTL; повторный ввод «мос» после стирания — мгновенно;
minChars, ограничениеlimit;- для локальных данных — фильтрация в памяти, для очень больших — Web Worker или индекс (trie).
Доступность (combobox):
input:role="combobox",aria-expanded,aria-controls,aria-activedescendant,aria-autocomplete="list";ul role="listbox", элементыrole="option"сaria-selected;- стрелки — перемещение, Enter — выбор, Esc — закрыть, Tab — уйти без выбора;
- фокус остается в поле; число результатов объявляется через
aria-live.
UX:
- подсветка совпадения без
innerHTML(безопасно от XSS); - последние запросы и популярные варианты при пустом вводе;
- позиционирование списка у края экрана (Floating UI), закрытие при клике вне;
- на мобильных — полноэкранный режим поиска,
inputMode,enterKeyHint="search".
Что важно помнить
- Три главных темы, которые ждут на интервью: debounce, отмена/гонки, кеш.
isOpenиactiveIndexсбрасываются при новом вводе и закрытии.- Компонент должен работать и в controlled-режиме (
value+onChange), и uncontrolled. - Ошибка сети не должна ломать ввод — показываем строку ошибки внутри списка.
- Связанные темы: debounce и throttle, отмена запросов.
Мини-шпаргалка
Headless-хук + разметка. debounce 200–300 мс, minChars, AbortController против гонок, LRU-кеш по нормализованному запросу. Combobox ARIA: aria-expanded, aria-activedescendant, listbox/option, стрелки/Enter/Esc. Состояния loading/empty/error, подсветка без innerHTML.
Документация
APG: Combobox Pattern, GreatFrontEnd: Front End System Design Playbook, Floating UI, MDN: AbortController.