Related components
RadioButtonField wraps a RadioButtonGroup to provide a legend and a InlineMessage. RadioButtonField.Item renders an individual RadioButton with an inline Label. It must be used inside a Form.
Note: a RadioButtonField.Item’s value must be a string.
<Form>
<RadioButtonField name="options" label="Please select an option">
<RadioButtonField.Item label="Option 1" value="1" />
<RadioButtonField.Item label="Option 2" value="2" />
</RadioButtonField>
</Form>
Default value
Use defaultValue to preselect an option.
<Form>
<RadioButtonField name="visibility" label="Who can see results?" defaultValue="teachers">
<RadioButtonField.Item label="Teachers only" value="teachers" />
<RadioButtonField.Item label="Teachers and pupils" value="pupils" />
<RadioButtonField.Item label="Teachers, pupils and parents" value="parents" />
</RadioButtonField>
</Form>
Description
Use description for extra context about the whole group. It sits between the legend and the options.
<Form>
<RadioButtonField
name="mode"
label="How will pupils take the assessment?"
description="You can change this until the assessment starts."
defaultValue="online"
>
<RadioButtonField.Item label="Online" value="online" />
<RadioButtonField.Item label="On paper" value="paper" />
</RadioButtonField>
</Form>
Direction
Options stack in a column by default. Set direction="row" to lay them out side by side.
<Form>
<RadioButtonField name="mode" label="How will pupils take the assessment?" direction="row" defaultValue="online">
<RadioButtonField.Item label="Online" value="online" />
<RadioButtonField.Item label="On paper" value="paper" />
</RadioButtonField>
</Form>
Size
Pass size to each RadioButtonField.Item: md (default) or lg.
<Form>
<RadioButtonField name="answer" label="Which number is a multiple of 7?">
<RadioButtonField.Item size="lg" label="24" value="24" />
<RadioButtonField.Item size="lg" label="35" value="35" />
<RadioButtonField.Item size="lg" label="48" value="48" />
</RadioButtonField>
</Form>
Validation
Pass validation to make the group required. The legend shows an asterisk, and the error shows under the options when the form is submitted.
<Form onSubmit={() => {}}>
<RadioButtonField
name="mode"
label="How will pupils take the assessment?"
validation={{ required: 'Choose how pupils will take the assessment' }}
>
<RadioButtonField.Item label="Online" value="online" />
<RadioButtonField.Item label="On paper" value="paper" />
</RadioButtonField>
<Button type="submit" className="mt-4">Set assessment</Button>
</Form>
Disabled
Disable one option with disabled on the RadioButtonField.Item, or the whole group with disabled on the RadioButtonField.
<div className="flex flex-col gap-6">
<Form>
<RadioButtonField name="mode" label="One option disabled" defaultValue="online">
<RadioButtonField.Item label="Online" value="online" />
<RadioButtonField.Item label="On paper (no printer set up)" value="paper" disabled />
</RadioButtonField>
</Form>
<Form>
<RadioButtonField name="mode" label="Whole group disabled" defaultValue="online" disabled>
<RadioButtonField.Item label="Online" value="online" />
<RadioButtonField.Item label="On paper" value="paper" />
</RadioButtonField>
</Form>
</div>
Listening for changes
If you need to know when the radio group value changes, you can pass onValueChange, which takes a string type as input.
const Example = () => {
const [value, setValue] = React.useState('teachers')
return (
<Form>
<RadioButtonField name="visibility" label="Who can see results?" defaultValue="teachers" onValueChange={setValue}>
<RadioButtonField.Item label="Teachers only" value="teachers" />
<RadioButtonField.Item label="Teachers and pupils" value="pupils" />
</RadioButtonField>
<Text size="sm" className="mt-4">Selected: {value}</Text>
</Form>
)
}
render(<Example />)