Related components

Radio Button


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 />)