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


function RadioGroupExample() {
  const [value, setValue] = useState('no');
  return (
    <Stack flexDirection="row">
      <Radio
        id="radio1"
        name="radio-controlled"
        value="yes"
        isChecked={value === 'yes'}
        onChange={() => setValue('yes')}
      >
        Yes
      </Radio>
      <Radio
        id="radio2"
        name="radio-controlled"
        value="no"
        isChecked={value === 'no'}
        onChange={() => setValue('no')}
      >
        No
      </Radio>
    </Stack>
  );
}function RadioGroupExample() {
  const [value, setValue] = useState('no');
  return (
    <Stack flexDirection="row">
      <Radio
        id="radio1"
        name="radio-controlled"
        value="yes"
        isChecked={value === 'yes'}
        onChange={() => setValue('yes')}
      >
        Yes
      </Radio>
      <Radio
        id="radio2"
        name="radio-controlled"
        value="no"
        isChecked={value === 'no'}
        onChange={() => setValue('no')}
      >
        No
      </Radio>
    </Stack>
  );
}

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.


function RadioUncontrolledExample() {
  return (
    <Stack flexDirection="row">
      <Radio
        id="radio1"
        name="radio-uncontrolled"
        value="yes"
        defaultChecked={true}
      >
        Yes
      </Radio>
      <Radio id="radio2" name="radio-uncontrolled" value="no">
        No
      </Radio>
    </Stack>
  );
}function RadioUncontrolledExample() {
  return (
    <Stack flexDirection="row">
      <Radio
        id="radio1"
        name="radio-uncontrolled"
        value="yes"
        defaultChecked={true}
      >
        Yes
      </Radio>
      <Radio id="radio2" name="radio-uncontrolled" value="no">
        No
      </Radio>
    </Stack>
  );
}

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.


function RadioGroupExample() {
  const [role, setRole] = useState('admin');
  return (
    <FormControl as="fieldset">
      <FormControl.Label as="legend" marginBottom="none">
        Permissions
      </FormControl.Label>
      <Paragraph>User permissions within this space</Paragraph>
      <Radio.Group
        name="permission"
        value={role}
        onChange={(e) => {
          setRole(e.target.value);
        }}
      >
        <Radio value="admin" helpText="Can create, modify and delete content">
          Admin
        </Radio>
        <Radio value="author" helpText="Can create and modify content">
          Author
        </Radio>
        <Radio
          value="translator"
          isDisabled
          helpText="Can only modify specific locale"
        >
          Translator (disabled)
        </Radio>
      </Radio.Group>
    </FormControl>
  );
}function RadioGroupExample() {
  const [role, setRole] = useState('admin');
  return (
    <FormControl as="fieldset">
      <FormControl.Label as="legend" marginBottom="none">
        Permissions
      </FormControl.Label>
      <Paragraph>User permissions within this space</Paragraph>
      <Radio.Group
        name="permission"
        value={role}
        onChange={(e) => {
          setRole(e.target.value);
        }}
      >
        <Radio value="admin" helpText="Can create, modify and delete content">
          Admin
        </Radio>
        <Radio value="author" helpText="Can create and modify content">
          Author
        </Radio>
        <Radio
          value="translator"
          isDisabled
          helpText="Can only modify specific locale"
        >
          Translator (disabled)
        </Radio>
      </Radio.Group>
    </FormControl>
  );
}

Props (API reference)

Radio

Open in Storybook

Name
aria-label
Description
Value to be set as aria-label if not passing a children
string
Name
className
Description
CSS class to be appended to the root element
string
Name
defaultChecked
Description
Defines initial checked state for an uncontrolled component
false
true
Name
helpText
Description
Optional text to be added as help text bellow the label
string
Name
id
Description
Sets the id of the input
string
Name
inputProps
Description
Additional props that are passed to the input element
Partial<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>>
Name
isChecked
Description
Defines if the element is checked, onChange will be required
false
true
Name
isDisabled
Description
Applies disabled styles
false
true
Name
isInvalid
Description
Applies invalid styles
false
true
Name
isRequired
Description
Validate the input
false
true
Name
label
string
Name
name
Description
Set the name of the input
string
Name
onBlur
Description
Allows to listen to an event when an element loses focus
FocusEventHandler<HTMLInputElement | HTMLTextAreaElement>
Name
onChange
Description
Allows to listen to an input’s change in value
ChangeEventHandler<HTMLInputElement>
Name
onFocus
Description
Allows to listen to an event when an element get focused
FocusEventHandler<HTMLInputElement | HTMLTextAreaElement>
Name
onKeyDown
Description
Allows to listen to an event when a key is pressed
KeyboardEventHandler<HTMLInputElement | HTMLTextAreaElement>
Name
resize
Description
Sets whether an element is resizable, and if so, in which directions
"none"
"both"
"horizontal"
"vertical"
Name
testId
Description
A [data-test-id] attribute used for testing purposes
string
Name
value
Description
Set the value of the input
string
Name
willBlurOnEsc
Description
Boolean property that allows to blur on escape
false
true

Radio.Group

Name
children(required)
Description
Elements that should be in the group
ReactNode
Name
className
Description
CSS class to be appended to the root element
string
Name
defaultValue
Description
Value of the radio that should be checked for uncontrolled inputs
string
Name
name
Description
Name that will be assigned to all checkboxes inside the group, unless a different name is passed to the checkbox
string
Name
onBlur
Description
Handler that will be triggered when any checkbox inside the group loses focus
FocusEventHandler<HTMLInputElement>
Name
onChange
Description
Handler that will be triggered when any checkbox inside the group has their checked state changed
ChangeEventHandler<HTMLInputElement>
Name
testId
Description
A [data-test-id] attribute used for testing purposes
string
Name
value
Description
Value of the radio that should be checked for controlled inputs
string

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">

Import

Examples

Using as a controlled input

Using as an uncontrolled input

Using with Radio.Group

Props (API reference)

Radio

aria-label

className

defaultChecked

helpText

id

inputProps

isChecked

isDisabled

isInvalid

isRequired

label

name

onBlur

onChange

onFocus

onKeyDown

resize

testId

value

willBlurOnEsc