Перейти к основному содержанию

Обзор

RadioGroup координирует значение, навигацию с клавиатуры и отправку формы своих дочерних элементов Radio.

Использование

Неконтролируемое состояние

Используйте defaultValue, чтобы задать начальную частоту выставления счетов. Группа управляет последующими изменениями.
name группы определяет выбранное значение при отправке формы. Задайте группе доступное имя и добавьте метку каждому переключателю.

Горизонтальная компоновка

По умолчанию группы используют вертикальный столбец. Установите orientation="horizontal" для строки. Свойство управляет визуальной компоновкой через data-orientation; оно не задаёт aria-orientation и не изменяет навигацию с помощью клавиатуры. Как горизонтальные, так и вертикальные клавиши со стрелками сохраняют существующее поведение Base UI, включая навигацию справа налево через DirectionProvider.
Стандартный промежуток остается одинаковым в обоих направлениях.

Структура

Поместите каждый Radio или Radio.Root внутрь группы и свяжите его с меткой. Используйте Radio.Indicator для создания пользовательского индикатора. RadioGroup и Radio экспортируются отдельно.
Задайте группе собственное доступное имя с помощью aria-label или aria-labelledby. В приведенных ниже примерах aria-labelledby связывает группу с легендой. Каждой радиокнопке также требуется собственное имя. Разместите свойства выбора в RadioGroup, а значения вариантов — в Radio.

Управляемое состояние

Передайте value и обновляйте его с помощью onValueChange, чтобы управлять той же частотой выставления счетов в состоянии React. Выбор принадлежит группе, а не отдельным переключателям.
onValueChange получает следующее значение и сведения о событии. Универсальный тип значения выводится из свойств. Используйте disabled для группы, чтобы отключить все варианты, или для отдельного переключателя, чтобы отключить один вариант. Клавиши со стрелками перемещаются между доступными вариантами и выбирают их; Tab выводит из группы. Установленная версия Base UI поддерживает клавиши со стрелками как по горизонтали, так и по вертикали. RadioGroup добавляет свойство orientation, влияющее только на визуальное отображение, не изменяя этот контракт управления с клавиатуры.

Интеграция с нативными элементами и сведения о событиях

RadioGroup по умолчанию отображает div. Нативные свойства и ref указывают на этот элемент; render компонует другой элемент и изменяет фактическую цель ref. inputRef указывает на представительный скрытый input дочернего переключателя, используя выбранный доступный вариант или доступный резервный вариант. Публичные типы включают обобщённые RadioGroupProps, RadioGroupState, RadioGroupChangeEventReason и RadioGroupChangeEventDetails. Обработчик обратного вызова получает исходные сведения о событии, включая нативный event, reason, cancel() и allowPropagation(). Отмените предлагаемое изменение перед обновлением управляемого состояния, если выбор должен быть отклонён. Сохраняйте name, form, required, disabled и readOnly в группе для существующего контракта формы Base UI. Выбранное значение отправляется под именем name; отключённые группы исключаются, а группы только для чтения сохраняют свой выбор. form поддерживает группу за пределами формы-владельца. Установленная версия не восстанавливает состояние группы автоматически при нативном сбросе формы. Сбрасывайте управляемое состояние из обработчика onReset формы, если этого требует ваш workflow. В изолированных фронтенд-компонентах поместите группу внутрь формы-владельца. Рендерер перенаправляет проверку required и блокирует явные ссылки form, которые иначе разрешаются в документе хоста. SegmentedControl — это удобная предустановка, собранная из этих примитивов для краткого взаимоисключающего выбора. Она использует семантику переключателей и требует доступного имени группы. Вкладки и навигация по панелям вкладок — это отдельные элементы управления.

Свойства

Справочная информация генерируется из публичных типов компонента. Собственные атрибуты, включая доступные имена и обработчики событий, также принимаются в частях, отображающих элементы.
string | ((state: RadioGroupState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
TValue
The uncontrolled value of the radio button that should be initially selected.To render a controlled radio group, use the value prop instead.
boolean
по умолчанию:"false"
Whether the component should ignore user interaction.
string
Identifies the form that owns the radio inputs. Useful when the radio group is rendered outside the form.
Ref<HTMLInputElement>
A ref to access the hidden input element.
string
Identifies the field when a form is submitted.
((value: TValue, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)
Callback fired when the value changes.
"horizontal" | "vertical"
по умолчанию:"vertical"
Visual layout direction, reflected in data-orientation. Does not change arrow-key navigation or set aria-orientation.
boolean
по умолчанию:"false"
Whether the user should be unable to select a different radio button in the group.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, RadioGroupState>
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.
boolean
по умолчанию:"false"
Whether the user must choose a value before submitting a form.
CSSProperties | ((state: RadioGroupState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
TValue
The controlled value of the radio item that should be currently selected.To render an uncontrolled radio group, use the defaultValue prop instead.