Radio is a form component, that shows a radio input with its label. It is used to allow users to choose single option from the list.

If you want to let a user select multiple options, use the Checkbox component.

Radio.Group is a component that makes it easier to handle group of radios.

Import

import { Radio } from '@contentful/f36-components';
// or
import { Radio } from '@contentful/f36-forms';

Examples

Using as a controlled input

Controlled components in React are those in which form data is handled by the component’s state.

For using the Radio as a controlled input, you need to:

  • Pass the isChecked property, with this property it will already be a controlled component;
  • Pass a onChange handler, so you can use it to update the value of isChecked;

Setting the isChecked will already define it as a controlled input.

Using as an uncontrolled input

Uncontrolled components are those for which the form data is handled by the DOM itself. “Uncontrolled” refers to the fact that these components are not controlled by React state.

You can use the Radio as an uncontrolled input, for that you can:

  • Set the defaultChecked property, it will ensure that the checked state can be altered normally.
  • Don't set the isChecked as it will make the input controlled.

Using with Radio.Group

We also provide the Radio.Group component that helps when using multiple radios. You can pass some common properties on the Radio.Group level and they will be passed to the radios inside the group.

  • spacing: This will set how much space should be between the inputs;
  • name: By setting this property on the Radio.Group level, you will set it automatically for all the radios in the group;
  • defaultValue: This accepts a value that set the defaultChecked property for the radio that have the same value (uncontrolled);
  • value: Same as defaultValue but this one sets the isChecked property, making the radio group controlled (controlled);
  • onChange: Handler that will be executed when any radio inside the group receives the event of change.

Radio.Group is a recommended way of using Radio when using it within forms.

Props (API reference)

Radio

Name

Type

Default

aria-label
string

Value to be set as aria-label if not passing a children

className
string

CSS class to be appended to the root element

defaultChecked
false
true

Defines initial checked state for an uncontrolled component

helpText
string

Optional text to be added as help text bellow the label

id
string

Sets the id of the input

inputProps
Partial<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>>

Additional props that are passed to the input element

isChecked
false
true

Defines if the element is checked, onChange will be required

isDisabled
false
true

Applies disabled styles

isInvalid
false
true

Applies invalid styles

isRequired
false
true

Validate the input

label
string

name
string

Set the name of the input

onBlur
FocusEventHandler<HTMLInputElement | HTMLTextAreaElement>

Allows to listen to an event when an element loses focus

onChange
ChangeEventHandler<HTMLInputElement>

Allows to listen to an input’s change in value

onFocus
FocusEventHandler<HTMLInputElement | HTMLTextAreaElement>

Allows to listen to an event when an element get focused

onKeyDown
KeyboardEventHandler<HTMLInputElement | HTMLTextAreaElement>

Allows to listen to an event when a key is pressed

resize
"none"
"both"
"horizontal"
"vertical"

Sets whether an element is resizable, and if so, in which directions

testId
string

A [data-test-id] attribute used for testing purposes

value
string

Set the value of the input

willBlurOnEsc
false
true

Boolean property that allows to blur on escape

Radio.Group

Name

Type

Default

children
required
ReactNode

Elements that should be in the group

className
string

CSS class to be appended to the root element

defaultValue
string

Value of the radio that should be checked for uncontrolled inputs

name
string

Name that will be assigned to all checkboxes inside the group, unless a different name is passed to the checkbox

onBlur
FocusEventHandler<HTMLInputElement>

Handler that will be triggered when any checkbox inside the group loses focus

onChange
ChangeEventHandler<HTMLInputElement>

Handler that will be triggered when any checkbox inside the group has their checked state changed

testId
string

A [data-test-id] attribute used for testing purposes

value
string

Value of the radio that should be checked for controlled inputs

Content guidelines

  • Use direct, succinct copy that helps a user to successfully complete a form
  • Do not use punctuation for labels
  • Use sentence style caps (in which only the first word of a sentence or term is capitalized)

Accessibility

  • To ensure Radio meets accessibility standards, provide name and id
  • When using Radio.Group it should be wrapped in a <FormControl as="fieldset"> and have a <FormControl.Label as="legend">