Skip to content

🎉 v5 release candidate is out! Head to the v5 documentation to get started.

Radio

Radio buttons allow the user to select one option from a set.

Use radio buttons when the user needs to see all available options. If available options can be collapsed, consider using a dropdown menu because it uses less space.

Radio buttons should have the most commonly used option selected by default.

RadioGroup

RadioGroup is a helpful wrapper used to group Radio components that provides an easier API, and proper keyboard accessibility to the group.

Gender
<FormControl component="fieldset">
  <FormLabel component="legend">Gender</FormLabel>
  <RadioGroup aria-label="gender" name="gender1" value={value} onChange={handleChange}>
    <FormControlLabel value="female" control={<Radio />} label="Female" />
    <FormControlLabel value="male" control={<Radio />} label="Male" />
    <FormControlLabel value="other" control={<Radio />} label="Other" />
    <FormControlLabel value="disabled" disabled control={<Radio />} label="(Disabled option)" />
  </RadioGroup>
</FormControl>

To lay out the buttons horizontally, set the row prop: <RadioGroup row />.

Standalone radio buttons

Radio can also be used standalone, without the RadioGroup wrapper.

Label placement

You can change the placement of the label with the FormControlLabel component's labelPlacement prop:

labelPlacement

Show error

In general, radio buttons should have a value selected by default. If this is not the case, you can display an error if no value is selected when the form is submitted:

Pop quiz: Material-UI is...

Choose wisely

<form onSubmit={handleSubmit}>
  <FormControl component="fieldset" error={error} className={classes.formControl}>
    <FormLabel component="legend">Pop quiz: Material-UI is...</FormLabel>
    <RadioGroup aria-label="quiz" name="quiz" value={value} onChange={handleRadioChange}>
      <FormControlLabel value="best" control={<Radio />} label="The best!" />
      <FormControlLabel value="worst" control={<Radio />} label="The worst." />
    </RadioGroup>
    <FormHelperText>{helperText}</FormHelperText>
    <Button type="submit" variant="outlined" color="primary" className={classes.button}>
      Check Answer
    </Button>
  </FormControl>
</form>

Customized radios

Here is an example of customizing the component. You can learn more about this in the overrides documentation page.

Gender
<FormControl component="fieldset">
  <FormLabel component="legend">Gender</FormLabel>
  <RadioGroup defaultValue="female" aria-label="gender" name="customized-radios">
    <FormControlLabel value="female" control={<StyledRadio />} label="Female" />
    <FormControlLabel value="male" control={<StyledRadio />} label="Male" />
    <FormControlLabel value="other" control={<StyledRadio />} label="Other" />
    <FormControlLabel
      value="disabled"
      disabled
      control={<StyledRadio />}
      label="(Disabled option)"
    />
  </RadioGroup>
</FormControl>

When to use

Accessibility

(WAI-ARIA: https://www.w3.org/TR/wai-aria-practices/#radiobutton)

  • All form controls should have labels, and this includes radio buttons, checkboxes, and switches. In most cases, this is done by using the <label> element (FormControlLabel).
  • When a label can't be used, it's necessary to add an attribute directly to the input component. In this case, you can apply the additional attribute (e.g. aria-label, aria-labelledby, title) via the inputProps property.
<RadioButton
  value="radioA"
  inputProps={{ 'aria-label': 'Radio A' }}
/>