Radio
A control that allows the user to select a single value from multiple options.Use the <Radio /> component when the user needs to choose a single option from a group of options. The radio will automatically render a visibly hidden <input type="radio"> to ensure events propagate correctly.
- In a "create"-form (new data being entered), no radio elements should be checked initially
- Prefer placing the radios underneath each other to aid scannability
- Always utilise at least two or more choices
- List radios in a logical order, e.g:
- Alphabetically
- Numerically
- Time-based
- Most to least likely to be checked
- Each option should be independent from every other option
The radio can be uncontrolled or controlled. Use the checked prop, along with onChange to take control of the state. In most cases, React recommends using controlled components to implement forms.
Tip: Wrap your radios with the RadioGroup component to manage the state more easily, and get the recommended layout out of the box.
There are two radio sizes, small and medium (default).
To customise or add more information to the radio label, you can pass in any other component via children.
In rare cases when you need to create a custom radio, you can use the <RadioPrimitive /> component. Don't forget to use a <label> in conjunction, with a htmlFor="RADIO_PRIMITIVE_ID_HERE" for accessibility.
The <RadioGroup /> component is a styled context provider to help manage the state of a controlled group of radios, using the React Context API. Each <Radio /> must have a unique value set.
It is recommended to wrap your radio group with a Fieldset, which lets you add a legend and will be read out as a "group" by some screen readers.
Use the size prop to control the input size of the nested radios of the radio group.
In rare cases you can add the horizontal prop to make the radios in the radio group stack horizontally. However – it's recommended to use the default vertical layout for the best readability and experience.
If you need validation on a radio group you can use the same validation props as Field; invalid and message.
Just like the Field, extra vertical space is added under each radio group by default. This prevents layout shifts when a validation message is displayed. You can turn this extra space off by setting keepSpaceForMessage to false.