# Listbox
## Кратко
`Listbox` — всегда видимый список, в котором выбирают один или несколько вариантов, как в нативном `select` с `size`. Фокус остаётся на списке, а активный вариант он указывает через `aria-activedescendant`.
## Импорт
```tsx
import { Listbox, ListboxGroup, ListboxOption, type ListboxGroupProps, type ListboxOptionProps, type ListboxProps, type ListboxValue } from '@vega-ui/react';
```
## Экспортируемые типы
- `ListboxProps`
- `ListboxOptionProps`
- `ListboxGroupProps`
- `ListboxValue`
## Базовое использование
```tsx
import { Listbox, ListboxOption } from '@vega-ui/react';
export default function BasicUsage() {
return (
Pickup pointCourier to the doorParcel locker
);
}
```
## Варианты
- Выбор: одно значение или массив с `multiple`
- Размер: `xs`, `sm`, `md`, `lg`, `xl`
- Содержимое: простой текст или разметка с `label` для поиска при вводе (typeahead)
## Пограничные случаи
- `value={null}` очищает контролируемый список с одиночным выбором, а `undefined` делает его неконтролируемым.
- Отключённый список отключает все свои варианты, каким бы ни был их собственный `disabled`.
- Варианты читаются из DOM при каждом нажатии клавиши, поэтому фильтрация и добавление не требуют регистрации.
- Высота задаётся обычным CSS на списке, и он прокручивается сам.
## Частые ошибки
- Список без `aria-label` или `aria-labelledby`.
- Одинаковый `value` у двух вариантов.
- `Listbox` для компактного поля формы, где лучше подходит [Select](https://vega-ui.dev/ru/components/select/).
## Примеры
### Базовый
#### Базовый: видимая метка
Список всегда виден, поэтому обычно стоит под видимым заголовком. `aria-labelledby` ссылается на этот текст и даёт списку доступное имя; варианты рендерятся из данных.
```tsx
import { Listbox, ListboxOption, Text } from '@vega-ui/react';
import { useId } from 'react';
const layouts = [
{ value: 'board', label: 'Board' },
{ value: 'list', label: 'List' },
{ value: 'timeline', label: 'Timeline' },
{ value: 'calendar', label: 'Calendar' },
];
export default function VisibleLabel() {
const labelId = useId();
return (
);
}
```
### Контролируемый/с состоянием
#### Контролируемый/с состоянием: значение со сбросом
Шрифтом владеет родитель, и превью ниже читает его. Сброс ставит `null`, что очищает контролируемый список с одиночным выбором; `undefined` сделал бы его неконтролируемым.
```tsx
import { Button, Listbox, ListboxOption, Text } from '@vega-ui/react';
import { useState } from 'react';
const fonts = [
{ value: 'serif', label: 'Serif', family: 'Georgia, serif' },
{ value: 'sans', label: 'Sans-serif', family: 'system-ui, sans-serif' },
{ value: 'mono', label: 'Monospace', family: 'ui-monospace, monospace' },
];
export default function ValueWithAReset() {
const [font, setFont] = useState('serif');
const current = fonts.find((item) => item.value === font);
return (
setFont(next ?? null)} style={{ border: '1px solid var(--separator-opaque)' }}>
{fonts.map((item) => (
{item.label}
))}
The quick brown fox jumps over the lazy dog.
);
}
```
#### Контролируемый/с состоянием: несколько вариантов
С `multiple` значение — массив. Родитель выводит из него количество и доплату, а очищает пустым массивом.
```tsx
import { Button, Listbox, ListboxOption, Text } from '@vega-ui/react';
import { useState } from 'react';
const toppings = [
{ value: 'cheese', label: 'Extra mozzarella', price: 1.5 },
{ value: 'mushrooms', label: 'Mushrooms', price: 1 },
{ value: 'olives', label: 'Black olives', price: 1 },
{ value: 'pepperoni', label: 'Pepperoni', price: 2 },
{ value: 'jalapenos', label: 'Jalapeños', price: 0.5 },
];
export default function SeveralChoices() {
const [selected, setSelected] = useState(['cheese']);
const total = toppings
.filter((item) => selected.includes(item.value))
.reduce((sum, item) => sum + item.price, 0);
return (
{toppings.map((item) => (
{item.label}
))}
{selected.length} selected · +${total.toFixed(2)}
);
}
```
### Форма/интеграция
#### Форма/интеграция: отправка выбора вместе с формой
`Listbox` не является полем формы, поэтому форма читает скрытые поля, отрендеренные из того же состояния, по одному на выбранное значение. `onReset` формы возвращает исходный выбор.
```tsx
import { Button, Listbox, ListboxOption, Text } from '@vega-ui/react';
import { FormEvent, useId, useState } from 'react';
const initialChannels = ['email'];
export default function ListboxInForm() {
const labelId = useId();
const [channels, setChannels] = useState(initialChannels);
const [submitted, setSubmitted] = useState('');
const onSubmit = (event: FormEvent) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
setSubmitted(data.getAll('channel').join(', ') || 'nothing');
};
const onReset = () => {
setChannels(initialChannels);
setSubmitted('');
};
return (
);
}
```
### Раскладка/оверлей
#### Раскладка/оверлей: группы и прокручиваемый список
`ListboxGroup` группирует аэропорты по странам и получает имя от своего заголовка через `aria-labelledby`. Высота списка — обычный CSS: список сам прокручивается и держит активный вариант в поле зрения при движении стрелками.
```tsx
import { Listbox, ListboxGroup, ListboxOption, Text } from '@vega-ui/react';
import { useId } from 'react';
const countries = [
{
name: 'France',
airports: [
{ code: 'CDG', name: 'Paris Charles de Gaulle' },
{ code: 'ORY', name: 'Paris Orly' },
{ code: 'NCE', name: 'Nice Côte d’Azur' },
{ code: 'LYS', name: 'Lyon Saint-Exupéry' },
],
},
{
name: 'Germany',
airports: [
{ code: 'FRA', name: 'Frankfurt' },
{ code: 'MUC', name: 'Munich' },
{ code: 'BER', name: 'Berlin Brandenburg' },
],
},
{
name: 'Japan',
airports: [
{ code: 'HND', name: 'Tokyo Haneda' },
{ code: 'NRT', name: 'Tokyo Narita' },
{ code: 'KIX', name: 'Osaka Kansai' },
],
},
];
export default function GroupsAndAScrollingList() {
const id = useId();
return (
{countries.map((country) => (
{country.name}
{country.airports.map((airport) => (
{airport.name}
{airport.code}
))}
))}
);
}
```
### Ошибка
#### Ошибка: пояснение к пустому обязательному выбору
Форма проверяет выбор при отправке, ставит списку `aria-invalid` и связывает сообщение через `aria-describedby`. Выбор тарифа снимает ошибку.
```tsx
import { Button, HelperText, Listbox, ListboxOption, Text } from '@vega-ui/react';
import { FormEvent, useId, useState } from 'react';
export default function ExplainAnEmptyRequiredChoice() {
const id = useId();
const errorId = `${id}-error`;
const [plan, setPlan] = useState(null);
const [invalid, setInvalid] = useState(false);
const [done, setDone] = useState(false);
const onChangeValue = (next: string | undefined) => {
setPlan(next ?? null);
setInvalid(false);
};
const onSubmit = (event: FormEvent) => {
event.preventDefault();
if (plan === null) {
setInvalid(true);
return;
}
setDone(true);
};
return (
);
}
```
### Отключённый
#### Отключённый: варианты, которые нельзя выбрать
Распроданные размеры остаются видимыми вместе с причиной, но отключены: клики их игнорируют, а стрелки пропускают.
```tsx
import { Listbox, ListboxOption, Text } from '@vega-ui/react';
import { useId } from 'react';
const sizes = [
{ value: 'xs', label: 'XS', stock: 0 },
{ value: 's', label: 'S', stock: 4 },
{ value: 'm', label: 'M', stock: 12 },
{ value: 'l', label: 'L', stock: 0 },
{ value: 'xl', label: 'XL', stock: 2 },
];
export default function DisabledOptions() {
const id = useId();
return (