This is version 4 beta of Forma 36Go back to last stable version 3
Forma 36

Radio

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 the user select multiple options, use the Checkbox component.
Radio.Group is a component that makes it easier to handle group of radios.

Table of contents

How to use Radio

  • Name should be the same on all Radio on the same Group.
  • You can use the Radio as a controlled or uncontrolled input.

Using as a controlled input

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.

const ExampleControlled = () => {
const [value, setValue] = useState(null);
return (
<React.Fragment>
<Radio
id="radio1"
name="radio-controlled"
value="yes"
isChecked={value === 'yes'}
onChange={(e) => setValue('yes')}
>
Yes
</Radio>
<Radio
id="radio2"
name="radio-controlled"
value="no"
isChecked={value === 'no'}
onChange={(e) => setValue('no')}
>
No
</Radio>
</React.Fragment>
);
};

Using as an uncontrolled input

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.
<React.Fragment>
<Radio id="radio1" name="radio-controlled" value="yes" defaultChecked={true}>
Yes
</Radio>
<Radio id="radio2" name="radio-controlled" value="no">
No
</Radio>
</React.Fragment>

Using with 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;
  • value: Same as defaultValue but this one sets the isChecked property, making the radio group controlled;
  • onChange: Handler that will be executed when any radio inside the group receives the event of change.

Code examples

const ExampleRadio = () => {
const [value, setValue] = useState(null);
return (
<React.Fragment>
<Radio
id="radio1"
name="radio"
value="yes"
isChecked={value === 'yes'}
onChange={(e) => setValue('yes')}
>
Yes
</Radio>
<Radio
id="radio2"
name="radio"
value="no"
isChecked={value === 'no'}
onChange={(e) => setValue('no')}
>
No
</Radio>
</React.Fragment>
);
};

Component variations

Checked or disabled

The Radio can be rendered as checked, with the isChecked property.

The Radio can be rendered as disabled with the isDisabled property.

Content recommendations

  • Use direct, succinct copy that helps the user to successfully complete the 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">

Props

Props Radio

NameRequiredDefaultTypeDescription
aria-labelstringValue to be set as aria-label if not passing a children
defaultCheckedfalse
false
true
Defines initial checked state for an uncontrolled component
helpTextstringOptional text to be added as help text bellow the label
idstringSets the id of the input
inputPropsPartial<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>>Additional props that are passed to the input element
isCheckedundefined
false
true
Defines if the element is checked, onChange will be required
isDisabledfalse
false
true
Applies disabled styles
isInvalidfalse
false
true
Applies invalid styles
isRequiredfalse
false
true
Validate the input
labelstring
namestringSet the name of the input
onBlurFocusEventHandler<HTMLInputElement | HTMLTextAreaElement>Allows to listen to an event when an element loses focus
onChangeChangeEventHandler<HTMLInputElement>Allows to listen to an input’s change in value
onFocusFocusEventHandler<HTMLInputElement | HTMLTextAreaElement>Allows to listen to an event when an element get focused
onKeyDownKeyboardEventHandler<HTMLInputElement | HTMLTextAreaElement>Allows to listen to an event when a key is pressed
resizevertical"none" | "both" | "horizontal" | "vertical"Sets whether an element is resizable, and if so, in which directions
valuestringSet the value of the input
willBlurOnEsctrue
false
true
Boolean property that allows to blur on escape
classNamestringCSS class to be appended to the root element
styleCSSPropertiesAccepts a JavaScript object with camelCased properties rather than a CSS string
testIdstringA [data-test-id] attribute used for testing purposes

Props Group

NameRequiredDefaultTypeDescription
defaultValuestringValue of the radio that should be checked for uncontrolled inputs
namestringName that will be assigned to all checkboxes inside the group, unless a different name is passed to the checkbox
onBlurFocusEventHandler<HTMLInputElement>Handler that will be triggered when any checkbox inside the group loses focus
onChangeChangeEventHandler<HTMLInputElement>Handler that will be triggered when any checkbox inside the group has their checked state changed
valuestringValue of the radio that should be checked for controlled inputs
childrenrequiredReactNodeElements that should be in the group
classNamestringCSS class to be appended to the root element
styleCSSPropertiesAccepts a JavaScript object with camelCased properties rather than a CSS string
testIdstringA [data-test-id] attribute used for testing purposes