Radio

Choose a single option from a list.

A radio group allows a user to select a single option from a list.

Fruit
<RadioGroup name="fruit" label="Fruit">
  <Radio value="apple">Apple</Radio>
  <Radio value="banana">Banana</Radio>
  <Radio value="orange">Orange</Radio>
</RadioGroup>

Orientation

The radio group can be laid out horizontally (default) or vertically using the orientation prop.

Horizontal

Fruit
<RadioGroup name="fruit" label="Fruit" orientation="horizontal">
  <Radio value="apple">Apple</Radio>
  <Radio value="banana">Banana</Radio>
  <Radio value="orange">Orange</Radio>
</RadioGroup>

Vertical

Fruit
<RadioGroup name="fruit" label="Fruit" orientation="vertical">
  <Radio value="apple">Apple</Radio>
  <Radio value="banana">Banana</Radio>
  <Radio value="orange">Orange</Radio>
</RadioGroup>

Validation

Radio groups support the same validation functions as the other form elements. The validate function receives the value of the currently selected Radio, or an empty string when nothing is selected. See the validation documentation for more details.

<RadioGroup
  name="plan"
  label="Plan"
  orientation="vertical"
  validate={(value) => {
    if (!value) {
      return 'Please select a plan';
    }
  }}
  isRequired
>
  <Radio value="starter">Starter</Radio>
  <Radio value="pro">Pro</Radio>
  <Radio value="enterprise">Enterprise</Radio>
</RadioGroup>
Plan (Required)

Other props

description

A description can be added to a Radio Group or an individual Radio Button to provide additional context.

Preferred contact methodWe will only contact you using your preferred method.
<RadioGroup
  name="contact"
  label="Preferred contact method"
  description="We will only contact you using your preferred method."
  orientation="vertical"
>
  <Radio value="email">Email</Radio>
  <Radio value="phone">Phone</Radio>
  <Radio value="post">Post</Radio>
</RadioGroup>
Preferred contact method
<RadioGroup
  name="contact"
  label="Preferred contact method"
  orientation="vertical"
>
  <Radio value="email">Email</Radio>
  <Radio
    value="phone"
    description="Only phone numbers within the EU are supported."
  >
    Phone
  </Radio>
  <Radio value="post">Post</Radio>
</RadioGroup>

defaultValue

The initially selected option can be set with the defaultValue prop, using the value of the target Radio.

Fruit
<RadioGroup name="fruit" label="Fruit" defaultValue="banana">
  <Radio value="apple">Apple</Radio>
  <Radio value="banana">Banana</Radio>
  <Radio value="orange">Orange</Radio>
</RadioGroup>

isRequired

A radio group can be marked as required by setting the isRequired prop to true.

Plan (Required)
<RadioGroup name="plan" label="Plan" orientation="vertical" isRequired>
  <Radio value="starter">Starter</Radio>
  <Radio value="pro">Pro</Radio>
  <Radio value="enterprise">Enterprise</Radio>
</RadioGroup>

isInvalid

When rendered inside a form, the radio group will automatically enter an invalid state and display the error message returned by the validate function. It is also possible to manually set the invalid state with isInvalid and errorMessage.

Plan (Required)
Please select a plan
<RadioGroup
  name="plan"
  label="Plan"
  orientation="vertical"
  errorMessage="Please select a plan"
  isInvalid
  isRequired
>
  <Radio value="starter">Starter</Radio>
  <Radio value="pro">Pro</Radio>
  <Radio value="enterprise">Enterprise</Radio>
</RadioGroup>

isDisabled

The entire group or individual options can be disabled.

Fruit (group disabled)
Fruit (option disabled)
// Entire group disabled
<RadioGroup name="fruit" label="Fruit" isDisabled>
  <Radio value="apple">Apple</Radio>
  <Radio value="banana">Banana</Radio>
  <Radio value="orange">Orange</Radio>
</RadioGroup>
 
// Individual option disabled
<RadioGroup name="fruit" label="Fruit">
  <Radio value="apple">Apple</Radio>
  <Radio value="banana" isDisabled>Banana</Radio>
  <Radio value="orange">Orange</Radio>
</RadioGroup>

Props

RadioGroup

PropTypeDescription
namestringThe name of the field submitted with form data.
labelReactNodeThe label for the group.
descriptionReactNodeAdditional context displayed below the options.
errorMessagestringThe error message to display when the group is invalid.
orientation'horizontal' | 'vertical'The layout direction of the radio options.
isRequiredbooleanWhether selecting an option is required.
isInvalidbooleanWhether the group is in an invalid state.
isDisabledbooleanWhether all options in the group are disabled.
defaultValuestringThe value of the option selected by default.
valuestringThe currently selected value (controlled).
onChange(value: string) => voidHandler called when the selected option changes.
validate(value: string) => string | undefinedValidation function run on form submission.

Radio

PropTypeDescription
valuestringThe value submitted with the form when this option is selected.
childrenReactNodeThe label for this option.
isDisabledbooleanWhether this individual option is disabled.