Radio

Radio is a form element used for selecting one option from a list.
Full keyboard navigation
Can be controlled and uncontrolled
Supports radio groups with custom rendering
Similar components:
CheckboxSwitchSelect


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 submitted.

Like all native inputs in React, Radio supports controlled and uncontrolled options. 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 and let the browser control the rest afterwards.

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 with the same name.

States

If there is an error related to the radio field, you can use a hasError flag. Usually, you would 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 background.

Composition

Most of the time you will be rendering groups of radio buttons, which can be done with RadioGroup component. It handles the selection of radio buttons and lets you receive the current value of the group. 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. That will resolve FormControl html tags correctly for a group of input fields.

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
Previous
Next