Radio
Radio is a form element used for selecting one option from a list.

Other available selection types:

Usage

Radio component works like native radio buttons, which means you can either use its value property to define what's going to be passed to the form when it's checked.

Like all native inputs in React, Radio supports controlled and uncontrolled variant. It becomes controlled when you use checked property, which means that you have to control it with your state. Uncontrolled variant is used when you use defaultChecked property, which lets you define the default state but let the browser control the rest.

Note: You shouldn't be using both properties at the same time and React will throw warning if that happens.

Since Radio is an exclusive selection - you can't deselect a checked item unless you select another one.

States

If there is an error related to the radio field, you can use an hasError flag. Usually, you may need this only when displaying a group of radio buttons, and you can likely use RadioGroup component for that instead.

In order to make Radio non-interactive, you can use disabled flag. Like in native radio buttons, it will prevent onChange handler from triggering.

Note: Disabled state fades the component content. Even though it's not required to have regular contrast ratio for disabled elements, still make sure it's not used over gray backgrounds.

Composition

In products, we are always working with radio buttons to select an option from the list and RadioGroup component does just that. It handles some properties of the Radio and syncs them across multiple radio buttons. At the same time it doesn't enforce any specific layout so you're free to use any layout components together with it.

As you can see, name and onChange properties apply to all Radio components within its scope. By selecting a specific Radio, you will get the currently selected value logged into console.

Same way as Radio can define it's checked value, RadioGroup supports value and defaultValue to control the selection in the options list.

If you need to provide a label for a group of radio buttons, you can use the FormControl utility with group flag turned on.

Favorite animals:

Most of the time products are using simple radio buttons with text labels but sometimes you might want to display rich content and make it selectable. Radio and RadioGroup support this use case with its composition approach, as RadioGroup supports any layout components and Radio renders any children as its content.

Accessibility

When using Radio without children – make sure to wrap it with a label element.

Properties

Radio properties:

NameTypeDefaultRequiredComment
childrenReactNode-false
onChange({ event, name, value }) => {}-falseChange handler
namestring-true
valuestring-false
checkedboolean, null-falseControlled checked state
defaultCheckedboolean-falseUncontrolled checked state
disabledboolean-false
hasErrorboolean-false
classNamestring-falseclassName for the root element
attributesobject-falseAttributes for the root element
inputAttributesobject-falseAttributes for the input element

RadioGroup properties:

NameTypeDefaultRequiredComment
childrenReactNode-false
onChange({ event, name, value }) => {}-falseChange handler
namestring-true
valuestring-false
defaultValuestring-false
disabledboolean-false
hasErrorboolean-false