Forms

Radio Group

Lets someone choose one option from a labelled group.

React Aria SourceView as Markdown Edit on GitHub

Use RadioGroup when someone must choose one value from a set of options. Pass a label to name the group, then add a RadioField for each option.

Radio Group: Basic

Open in playground

Text alignment

Left

Centre

Right

import { RadioField, RadioGroup } from '@luke-ui/react/radio-group';

export default () => {
	return (
		<RadioGroup label="Text alignment" name="alignment">
			<RadioField label="Left" value="left" />
			<RadioField label="Centre" value="centre" />
			<RadioField label="Right" value="right" />
		</RadioGroup>
	);
};

Radio Group: Basic

Loading Radio Group: Basic example

Options

Pass a value to each RadioField. Each option can have a description beneath its label. Use orientation="horizontal" for a short set of options that fits in a row. The default orientation is vertical, and a horizontal group wraps when it runs out of space.

Radio Group: Orientations

Open in playground

import { RadioField, RadioGroup } from '@luke-ui/react/radio-group';
import { Comparison, ComparisonItem } from '#docs';

export default () => {
	return (
		<Comparison>
			<ComparisonItem label="Vertical">
				<RadioGroup label="Text alignment">
					<RadioField label="Left" value="left" />
					<RadioField label="Centre" value="centre" />
					<RadioField label="Right" value="right" />
				</RadioGroup>
			</ComparisonItem>
			<ComparisonItem label="Horizontal">
				<RadioGroup label="Text alignment" orientation="horizontal">
					<RadioField label="Left" value="left" />
					<RadioField label="Centre" value="centre" />
					<RadioField label="Right" value="right" />
				</RadioGroup>
			</ComparisonItem>
		</Comparison>
	);
};

Radio Group: Orientations

Loading Radio Group: Orientations example

Selection

Use defaultValue for an uncontrolled initial choice. Pair value with onChange when application state owns the choice. The selected option's value is submitted with the group's name.

Radio Group: Controlled

Open in playground

Text alignment

Left

Centre

Right

Selected alignment: left

import { RadioField, RadioGroup } from '@luke-ui/react/radio-group';
import { Stack } from '@luke-ui/react/stack';
import { Text } from '@luke-ui/react/text';
import { useState } from 'react';

export default () => {
	const [alignment, setAlignment] = useState('left');

	return (
		<Stack gap="space.16">
			<RadioGroup label="Text alignment" onChange={setAlignment} value={alignment}>
				<RadioField label="Left" value="left" />
				<RadioField label="Centre" value="centre" />
				<RadioField label="Right" value="right" />
			</RadioGroup>
			<Text color="secondary" elementType="p" role="status">
				{`Selected alignment: ${alignment}`}
			</Text>
		</Stack>
	);
};

Radio Group: Controlled

Loading Radio Group: Controlled example

Size

Set size on the group to size every option. Set it on a RadioField to override the group size. The size does not change option label typography. When neither sets a size, the group inherits Form.controlSize or uses medium.

Radio Group: Sizes

Open in playground

Small

Text alignment

Left

Right

Medium

Text alignment

Left

Right

import { RadioField, RadioGroup } from '@luke-ui/react/radio-group';
import { Comparison, ComparisonItem } from '#docs';

export default () => {
	return (
		<Comparison>
			<ComparisonItem label="Small">
				<RadioGroup label="Text alignment" size="small">
					<RadioField label="Left" value="left" />
					<RadioField label="Right" value="right" />
				</RadioGroup>
			</ComparisonItem>
			<ComparisonItem label="Medium">
				<RadioGroup label="Text alignment" size="medium">
					<RadioField label="Left" value="left" />
					<RadioField label="Right" value="right" />
				</RadioGroup>
			</ComparisonItem>
		</Comparison>
	);
};

Radio Group: Sizes

Loading Radio Group: Sizes example

Validation

Set isRequired when the group needs a choice before the form submits. Pass validate for a custom rule. Pass errorMessage for an error from a form library or server. A non-empty message marks the group invalid and shows one message beneath its options. The group description remains visible when the group is invalid. Read Validation for where messages come from and how to write them.

By default, a required group shows a marker after its label. Read Required fields for the necessityIndicator values.

Submit without choosing an option to see the validation message.

Radio Group: Validation

Open in playground

import { Button } from '@luke-ui/react/button';
import { Cluster } from '@luke-ui/react/cluster';
import { RadioField, RadioGroup } from '@luke-ui/react/radio-group';
import { Stack } from '@luke-ui/react/stack';
import type { SubmitEvent } from 'react';

function handleSubmit(event: SubmitEvent<HTMLFormElement>) {
	event.preventDefault();
}

export default () => {
	return (
		<form onSubmit={handleSubmit}>
			<Stack gap="space.16">
				<RadioGroup isRequired label="Text alignment" name="alignment">
					<RadioField label="Left" value="left" />
					<RadioField label="Centre" value="centre" />
					<RadioField label="Right" value="right" />
				</RadioGroup>
				<Cluster>
					<Button type="submit">Submit</Button>
				</Cluster>
			</Stack>
		</form>
	);
};

Radio Group: Validation

Loading Radio Group: Validation example

Accessibility

Give the group a visible label, or use aria-label or aria-labelledby when another part of the layout already names it. Use RadioField for each option so its visible label and optional description stay connected to its radio control. The group supports arrow-key navigation. Disabled groups keep their options disabled even if an individual option sets isDisabled={false}.

For a custom layout, compose the Radio primitive.

API

RadioGroupProps

RadioGroupProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type	Default
description	ReactNode	—
Optional helper text shown below the control.
errorMessage	ReactNode	—
Validation message for a controlled error. A non-empty message marks the group invalid.
label	Exclude<ReactNode, boolean \|⁠ null \|⁠ undefined>	—
Visible label. Pass non-empty, textual, non-interactive content. Place links and buttons outside it, and associate external label content with `aria-labelledby` instead.
necessityIndicator		—
Controls how the label identifies required or optional values. Inherits from `Form`, or uses `'required-asterisk'` when unset.
orientation	Orientation \|⁠ undefined	—
The group layout and keyboard-navigation direction.
size		`'medium'`
Visual size supplied to options that do not set their own size.

RadioFieldProps

RadioFieldProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type
description	ReactNode
Supporting text shown beneath the option label.
inputId	string \|⁠ undefined
Element id for the input.
inputRef	React.Ref<HTMLInputElement \|⁠ null> \|⁠ undefined
Forwarded to the hidden radio input.
label*	Exclude<ReactNode, boolean \|⁠ null \|⁠ undefined>
Visible option label. Pass non-empty, textual, non-interactive content. Place links and buttons outside the label.
size	"medium" \|⁠ "small" \|⁠ undefined
Visual size of the radio option. Defaults to the group size, then `Form.controlSize`, then `medium`.