# Select ## Кратко `Select` — [составной компонент](https://vega-ui.dev/ru/docs/glossary/#составной-компонент-compound-component) из корневого контейнера состояния и экспортируемых дочерних частей для триггера, значения, вариантов и нативного [участия в форме](https://vega-ui.dev/ru/docs/glossary/#участие-в-форме-form-participation). `SelectListbox` рендерится в top layer браузера через `popover="manual"`, поэтому его никогда не обрезает `overflow` и не перекрывает модальный диалог. Это слой одиночного выбора, ориентированный на поля, а не универсальный примитив для плавающего содержимого. ## Импорт ```tsx import { Select, SelectCombobox, SelectHiddenSelect, SelectIcon, SelectListbox, SelectOption, SelectValue, type SelectProps, type SelectSize, type SelectVariant, } from '@vega-ui/react'; ``` ## Экспортируемые типы - `SelectProps` - `SelectSize = 'sm' | 'md' | 'lg' | string` - `SelectVariant = 'inline' | 'field' | string` ## Минимальная композиция ```tsx import { Label, Select, SelectCombobox, SelectHiddenSelect, SelectIcon, SelectListbox, SelectOption, SelectValue, } from '@vega-ui/react'; import { useId } from 'react'; export default function MinimalComposition() { const id = useId(); return (
); } ``` ## Обязательные части - `Select`: корневое состояние и провайдер контекста - `SelectCombobox`: поверхность триггера - `SelectValue`: выбранное значение или плейсхолдер - `SelectListbox`: контейнер вариантов - `SelectOption`: выбираемый вариант ## Необязательные части - `SelectHiddenSelect`: нативное [участие в форме](https://vega-ui.dev/ru/docs/glossary/#участие-в-форме-form-participation) - `SelectIcon`: визуальная подсказка триггера ## Порядок композиции Типичная композиция: 1. `Select` 2. `SelectHiddenSelect` 3. `SelectCombobox` 4. `SelectListbox` 5. `SelectOption` ## Варианты - Размер: `sm`, `md`, `lg` - Вариант: `field`, `inline` - Варианты состояния: [контролируемое](https://vega-ui.dev/ru/docs/glossary/#контролируемый-controlled) значение, [контролируемое](https://vega-ui.dev/ru/docs/glossary/#контролируемый-controlled) состояние открытия, [отключённый](https://vega-ui.dev/ru/docs/glossary/#отключённый-disabled), [только для чтения](https://vega-ui.dev/ru/docs/glossary/#только-для-чтения-read-only), композиция с поиском ## Пограничные случаи - `disabled` полностью блокирует взаимодействие; `readOnly` сохраняет фокусируемость, но запрещает изменения. См. [Отключённый](https://vega-ui.dev/ru/docs/glossary/#отключённый-disabled) и [Только для чтения](https://vega-ui.dev/ru/docs/glossary/#только-для-чтения-read-only). - При фильтрации внутри списка встроенный [поиск при наборе](https://vega-ui.dev/ru/docs/glossary/#поиск-по-вводу-typeahead) обычно стоит отключить через `typeahead={false}`, чтобы избежать конфликтов клавиатуры. - Значения типизированы как `string | number`; значения-объекты публичный API не поддерживает. - `SelectHiddenSelect` рекомендуется, когда значение должно участвовать в нативном [участии в форме](https://vega-ui.dev/ru/docs/glossary/#участие-в-форме-form-participation). - Если продукту нужно более богатое произвольное содержимое оверлея, а не одно скалярное значение, правильная абстракция — обычно `Popover` или `Dialog`, а не `Select`. ## Частые ошибки - Передача значений-объектов вместо `string` или `number`. - Отсутствие `SelectHiddenSelect` в сценариях с нативной формой. - Включённый встроенный [поиск при наборе](https://vega-ui.dev/ru/docs/glossary/#поиск-по-вводу-typeahead) при встраивании поля поиска в список. - Использование `readOnly`, когда задумано полностью [отключённое](https://vega-ui.dev/ru/docs/glossary/#отключённый-disabled) состояние элемента. ## Примеры ### Базовый #### Базовый: вариант field с видимой меткой Видимый `Label` ссылается на `SelectCombobox` по `id` и даёт триггеру доступное имя. Варианты рендерятся из данных, а плейсхолдер виден, пока пользователь не выберет команду. ```tsx import { Label, Select, SelectCombobox, SelectIcon, SelectListbox, SelectOption, SelectValue, } from '@vega-ui/react'; import { useId } from 'react'; const teams = [ { value: 'billing', label: 'Billing' }, { value: 'onboarding', label: 'Onboarding' }, { value: 'platform', label: 'Platform reliability' }, { value: 'security', label: 'Security & compliance' }, { value: 'success', label: 'Customer success' }, ]; export default function FieldVariant() { const id = useId(); return (
); } ``` ### Контролируемый/с состоянием #### Контролируемый/с состоянием: контролируемое значение с действием очистки Приоритетом владеет родитель и выводит из него срок ответа. Очистка ставит значение в `null`: `undefined` переключил бы Select в неконтролируемый режим и оставил бы старый выбор. ```tsx import { Button, Label, Select, SelectCombobox, SelectIcon, SelectListbox, SelectOption, SelectValue, Text, } from '@vega-ui/react'; import { useId, useState } from 'react'; const priorities = [ { value: 'low', label: 'Low', response: 'within 3 business days' }, { value: 'normal', label: 'Normal', response: 'within 1 business day' }, { value: 'urgent', label: 'Urgent', response: 'within 1 hour' }, ]; export default function ControlledValueWithClearAction() { const id = useId(); const [priority, setPriority] = useState('normal'); const current = priorities.find((item) => item.value === priority); return (
{current ? `First response ${current.response}.` : 'No priority: the ticket waits in the general queue.'}
); } ``` #### Контролируемый/с состоянием: контролируемое состояние открытия `open` и `onChangeOpen` позволяют открыть список из другого элемента. Кнопка сначала переводит фокус на триггер, поэтому стрелки и Enter сразу работают, а подсказка видна, только пока список открыт. ```tsx import { Button, Label, Select, SelectCombobox, SelectIcon, SelectListbox, SelectOption, SelectValue, Text, } from '@vega-ui/react'; import { useId, useRef, useState } from 'react'; export default function ControlledOpenState() { const id = useId(); const comboboxRef = useRef(null); const [open, setOpen] = useState(false); const [reviewer, setReviewer] = useState(null); const chooseReviewer = () => { comboboxRef.current?.focus(); setOpen(true); }; return (
{reviewer === null && (
Needs one review.
)} {open && ( Arrow keys move through the list, Enter picks, Escape closes. )}
); } ``` ### Форма/интеграция #### Форма/интеграция: участие в нативной форме `SelectHiddenSelect` с `name` кладёт каждое значение в `FormData`, и обработчик отправки читает Select как нативные поля. У каждого триггера своя `Label`. ```tsx import { Button, Label, Select, SelectCombobox, SelectHiddenSelect, SelectIcon, SelectListbox, SelectOption, SelectValue, Text, } from '@vega-ui/react'; import { FormEvent, useId, useState } from 'react'; export default function NativeFormParticipation() { const planId = useId(); const cycleId = useId(); const [submitted, setSubmitted] = useState(''); const onSubmit = (event: FormEvent) => { event.preventDefault(); const data = new FormData(event.currentTarget); setSubmitted(`plan=${data.get('plan')}, cycle=${data.get('cycle')}`); }; return (
{submitted && ( Submitted: {submitted} )}
); } ``` ### Раскладка/оверлей #### Раскладка/оверлей: вариант inline внутри интерфейса в виде предложения `variant='inline'` встраивает Select в предложение. Окружающий текст не является меткой, поэтому у триггера свой `aria-label`. ```tsx import { Select, SelectCombobox, SelectHiddenSelect, SelectIcon, SelectListbox, SelectOption, SelectValue, Text, } from '@vega-ui/react'; export default function InlineVariantInsideSentenceLikeUi() { return (
Email me a digest
); } ``` #### Раскладка/оверлей: select внутри диалога Список открывается в верхнем слое поверх модального диалога, портал не нужен. Форма внутри диалога читает значение через `FormData` и закрывает диалог при отправке. ```tsx import type { CSSProperties, FormEvent } from 'react'; import { Button, Dialog, DialogClose, DialogContent, DialogTrigger, Heading, Icon, IconButton, Label, Select, SelectCombobox, SelectHiddenSelect, SelectIcon, SelectListbox, SelectOption, SelectValue, Text, } from '@vega-ui/react'; import { XIcon } from '@vega-ui/icons'; import { useId, useState } from 'react'; export default function SelectInsideDialog() { const id = useId(); const [open, setOpen] = useState(false); const [exported, setExported] = useState(''); const onSubmit = (event: FormEvent) => { event.preventDefault(); const data = new FormData(event.currentTarget); setExported(`Exporting the Q3 report as ${data.get('format')}.`); setOpen(false); }; return (
Export Q3 report
{exported && {exported}}
); } ``` #### Раскладка/оверлей: свой Select в каждой строке таблицы В каждой строке свой Select, который меняет одного участника в состоянии родителя. Каждый триггер назван по своей строке, и скринридер объявляет «Role of Mei Tanaka», а не ряд одинаковых полей «Role». ```tsx import { Select, SelectCombobox, SelectIcon, SelectListbox, SelectOption, SelectValue, Table, TableBody, TableData, TableHead, TableHeading, TableRow, Text, } from '@vega-ui/react'; import { useState } from 'react'; const initialMembers = [ { id: 'u1', name: 'Amara Okafor', email: 'amara@northwind.io', role: 'owner' }, { id: 'u2', name: 'Lucas Moreau', email: 'lucas@northwind.io', role: 'editor' }, { id: 'u3', name: 'Mei Tanaka', email: 'mei@northwind.io', role: 'viewer' }, ]; export default function SelectInTableRows() { const [members, setMembers] = useState(initialMembers); const changeRole = (id: string, role: string | undefined) => { if (role === undefined) return; setMembers((current) => current.map((member) => (member.id === id ? { ...member, role } : member))); }; return ( Member Role {members.map((member) => (
{member.name} {member.email}
))}
); } ``` ### Ошибка #### Ошибка: обязательный выбор со связанным сообщением Форма проверяет значение при отправке, помечает триггер `aria-invalid`, связывает сообщение через `aria-describedby` и возвращает фокус на поле. Выбор любого варианта снимает ошибку. ```tsx import { Button, HelperText, Label, Select, SelectCombobox, SelectHiddenSelect, SelectIcon, SelectListbox, SelectOption, SelectValue, Text, } from '@vega-ui/react'; import { FormEvent, useId, useRef, useState } from 'react'; export default function SelectRequiredError() { const id = useId(); const errorId = `${id}-error`; const comboboxRef = useRef(null); const [reason, setReason] = useState(null); const [invalid, setInvalid] = useState(false); const [sent, setSent] = useState(false); const onChangeValue = (next: string | undefined) => { setReason(next ?? null); setInvalid(false); }; const onSubmit = (event: FormEvent) => { event.preventDefault(); if (reason === null) { setInvalid(true); comboboxRef.current?.focus(); return; } setSent(true); }; return (
{invalid && ( Choose a reason so we can route your feedback. )} {sent && ( Your subscription ends on the last day of the billing period. )}
); } ``` ### Отключённый #### Отключённый: унаследовано от fieldset Триггер — нативная кнопка, поэтому отключённый `Fieldset` отключает её вместе со скрытым select: поле не открывается и не попадает в `FormData`. Переключатель меняет это состояние. ```tsx import { Fieldset, Label, Select, SelectCombobox, SelectHiddenSelect, SelectIcon, SelectListbox, SelectOption, SelectValue, Switch, SwitchIndicator, SwitchInput, } from '@vega-ui/react'; import { useId, useState } from 'react'; export default function FullyDisabledField() { const switchId = useId(); const selectId = useId(); const [useDefault, setUseDefault] = useState(true); return (
setUseDefault(event.currentTarget.checked)} />
); } ``` #### Отключённый: значение только для чтения с пояснением `readOnly` оставляет триггер фокусируемым, а значение — в отправке формы, но список не открывается. Причина связана с триггером через `aria-describedby`. ```tsx import { HelperText, Label, Select, SelectCombobox, SelectHiddenSelect, SelectIcon, SelectListbox, SelectOption, SelectValue, } from '@vega-ui/react'; import { useId } from 'react'; export default function ReadOnlyField() { const id = useId(); const hintId = `${id}-hint`; return (
Locked after the first invoice. Contact support to change it.
); } ``` ### Пограничный случай #### Пограничный случай: сотни вариантов 288 слотов времени с шагом пять минут. Список прокручивается сам, открывается на выбранном варианте, а typeahead переходит к слоту: наберите «14», чтобы попасть на 14:00. ```tsx import { Label, Select, SelectCombobox, SelectHiddenSelect, SelectIcon, SelectListbox, SelectOption, SelectValue, } from '@vega-ui/react'; import { useId } from 'react'; const slots = Array.from({ length: 24 * 12 }, (_, index) => { const hours = String(Math.floor(index / 12)).padStart(2, '0'); const minutes = String((index % 12) * 5).padStart(2, '0'); return `${hours}:${minutes}`; }); export default function LongScrollableOptionList() { const id = useId(); return (
); } ``` #### Пограничный случай: короткий текст значения для длинных вариантов Без дочерних элементов `SelectValue` копирует выбранный вариант на клиенте. Дочерние элементы заменяют эту копию: длинные варианты могут оставлять триггер коротким, а значение рендерится и на сервере; пока ничего не выбрано, по-прежнему показывается плейсхолдер. ```tsx import { Select, SelectCombobox, SelectIcon, SelectListbox, SelectOption, SelectValue, } from '@vega-ui/react'; import { useState } from 'react'; export default function CustomValueText() { const [currency, setCurrency] = useState('EUR'); return ( ); } ``` #### Пограничный случай: варианты загружаются при открытии списка Проекты запрашиваются при первом открытии, на время загрузки у списка `aria-busy` и спиннер. Сохранённого выбора ещё нет среди отрендеренных вариантов, поэтому его название передаётся в `SelectValue` дочерним элементом. ```tsx import { Label, Select, SelectCombobox, SelectIcon, SelectListbox, SelectOption, SelectValue, Spinner, Text, } from '@vega-ui/react'; import { useId, useState } from 'react'; interface Project { id: string; name: string; } const fetchProjects = () => new Promise((resolve) => { setTimeout(() => resolve([ { id: 'apollo', name: 'Apollo website' }, { id: 'borealis', name: 'Borealis mobile app' }, { id: 'cobalt', name: 'Cobalt billing API' }, { id: 'delta', name: 'Delta data warehouse' }, ]), 1200); }); export default function AsyncOptions() { const id = useId(); const [projects, setProjects] = useState(null); const [loading, setLoading] = useState(false); const [project, setProject] = useState({ id: 'apollo', name: 'Apollo website' }); const onChangeOpen = (open: boolean) => { if (!open || projects !== null || loading) return; setLoading(true); fetchProjects().then((result) => { setProjects(result); setLoading(false); }); }; const onChangeValue = (next: string | undefined) => { const found = projects?.find((item) => item.id === next); setProject(found ?? null); }; return (
); } ``` ## Анатомия ### Обзор `Select` — составной компонент. Корень отвечает за состояние открытия, состояние выбора, регистрацию вариантов, навигацию с клавиатуры и поиск при наборе. Экспортируемые дочерние части используют этот общий контекст. ### Обязательные части #### `Select` Корневой провайдер всей композиции. - Обязательна: да - Отвечает за: выбранное значение, состояние открытия, активный вариант, взаимодействие с клавиатуры - Должна оборачивать все остальные части `Select*` #### `SelectCombobox` Видимая поверхность триггера, открывающая и закрывающая список. - Обязательна: да - Типичные дочерние элементы: `SelectValue`, `SelectIcon` - Должна оставаться внутри `Select` #### `SelectValue` Рендерит текущее значение или плейсхолдер. - Обязательна: фактически да в большинстве интерфейсов - Принимает собственные дочерние элементы, когда выбранное значение нужно отрендерить богаче - Должна оставаться внутри `SelectCombobox` #### `SelectIcon` Необязательный визуальный индикатор триггера. - Обязательна: нет - Обычно размещается после `SelectValue` #### `SelectListbox` Контейнер для выбираемых вариантов. - Обязательна: да - Должна содержать один или несколько дочерних `SelectOption` - Рендерится в top layer через `popover="manual"`, поэтому отдельная часть-портал не нужна - Сама управляет фокусом: стрелки перемещают фокус по вариантам, а при закрытии списка фокус возвращается на `SelectCombobox` #### `SelectOption` Выбираемый элемент, регистрируемый в модели вариантов корня. - Обязательна: да - Должна рендериться внутри `SelectListbox` - Тип значения должен соответствовать `string | number` ### Необязательные части #### `SelectHiddenSelect` Скрытый нативный select для отправки формы и браузерной семантики форм. - Обязательна: нет - Рекомендуется: да, для нативных форм - Опускайте, только когда компонент используется вне обычной отправки формы #### `SelectIcon` Необязательный визуальный индикатор триггера. - Обязательна: нет - Обычно размещается после `SelectValue` ### Порядок композиции Типичная композиция: 1. `Select` 2. `SelectHiddenSelect` 3. `SelectCombobox` 4. `SelectListbox` 5. `SelectOption` ### Корректные варианты композиции ```tsx import { Label, Select, SelectCombobox, SelectHiddenSelect, SelectIcon, SelectListbox, SelectOption, SelectValue, } from '@vega-ui/react'; import { useId } from 'react'; export default function MinimalComposition() { const id = useId(); return (
); } ``` Все части на своих местах: `Label` называет триггер через его `id`, а `SelectHiddenSelect` с `name` отправляет значение вместе с формой. Опускайте только скрытый select, если значение никогда не проходит через форму. ### Некорректные варианты композиции #### `SelectOption` вне `SelectListbox` Это ломает регистрацию вариантов и навигацию с клавиатуры. #### `SelectValue` вне `SelectCombobox` Это нарушает контракт композиции триггера и делает размещение выбранного значения неоднозначным. #### Дочерние части вне `Select` Публичные части опираются на контекст корня. Рендер вне `Select` ломает поведение. #### Поле поиска без отключения поиска при наборе Если внутри `SelectListbox` рендерится текстовое поле, встроенный поиск при наборе обычно стоит отключить через `typeahead={false}`.