Skip Navigation
React Magma

Radio Button

Radio buttons are form elements used to select one item from a set of mutually exclusive options.

Basic Usage

The RadioGroup component is used as the container for the set of options. The Radio component is used for each of the options themselves.

See also: Checkboxes and Toggle Switches.

The label/radio association will be handled via the passed in id if one is supplied or via an auto-generated id if not supplied.

import React from 'react';


import { RadioGroup, Radio } from 'react-magma-dom';


export function Example() {
  return (
    <RadioGroup labelText="Basic usage" id="basicGroup" name="basic">
      <Radio id="radio1" labelText="Option one label" value="1" />


      <Radio
        id="radio2"
        labelText="Option two label is really long and can wrap to multiple lines lorem ipsum dolar sit amet is really long and can wrap to multiple lines"
        value="2"
      />
    </RadioGroup>
  );
}

Default Selected Value

To set a selected value by default, use the value prop on the RadioGroup to pass in the value of the option you wish to select.

import React from 'react';


import { RadioGroup, Radio } from 'react-magma-dom';


export function Example() {
  return (
    <RadioGroup
      labelText="Default selected value"
      id="defaultSelectedGroup"
      name="defaultSelected"
      value="selectedOption"
    >
      <Radio
        id="radioSelected"
        labelText="Selected option"
        value="selectedOption"
      />


      <Radio
        id="radioUnselected"
        labelText="Unselected option"
        value="unselectedOption"
      />
    </RadioGroup>
  );
}

Colors

By default, the radio buttons use the theme's primary color. But any other color may be passed in.

import React from 'react';


import { RadioGroup, Radio, magma } from 'react-magma-dom';


export function Example() {
  return (
    <RadioGroup labelText="Colors" id="colorsGroup" name="colors">
      <Radio id="colorRadio" labelText="Default color" value="default" />
      <Radio
        color={magma.colors.success}
        id="successColorRadio"
        labelText="Success color"
        value="success"
      />
      <Radio
        color={magma.colors.danger}
        id="dangerColorRadio"
        labelText="Danger color"
        value="danger"
      />
    </RadioGroup>
  );
}

Disabled

import React from 'react';


import { RadioGroup, Radio } from 'react-magma-dom';


export function Example() {
  return (
    <RadioGroup
      labelText="Disabled radio buttons"
      id="disabledGroup"
      name="disabled"
      value="selectedOption"
    >
      <Radio
        disabled
        id="disabledRadio"
        labelText="Disabled radio 1"
        value="1"
      />
      <Radio
        disabled
        id="disabledRadio2"
        labelText="Disabled radio 2"
        value="2"
      />
      <Radio
        disabled
        id="disabledRadio3"
        labelText="Disabled radio 3 selected"
        value="selectedOption"
      />
    </RadioGroup>
  );
}

Helper Message

The helperMessage appears underneath the group of radio buttons. It will not appear if an error message is present. Can be a node or a string.

import React from 'react';


import { RadioGroup, Radio } from 'react-magma-dom';


export function Example() {
  return (
    <RadioGroup
      helperMessage="Your choice of color is important"
      labelText="Choose a color"
      name="helperMessage"
    >
      <Radio labelText="Red" value="R" />
      <Radio labelText="Blue" value="B" />
      <Radio labelText="Yellow" value="Y" />
    </RadioGroup>
  );
}

Required Fields / Error Message

The required attribute can be indicated to the RadioGroup component if a selection is required. You will also need to indicate the required field to the user in the UI.

If a radio group has an errorMessage, the radio buttons will be styled to highlight the error state and the error message will appear below the fields. If an error message is present, it will replace the helper text. Can be a node or a string.

import React from 'react';


import {
  RadioGroup,
  Radio,
  Button,
  ButtonColor,
  ButtonGroup,
} from 'react-magma-dom';


export function Example() {
  const [hasError, setHasError] = React.useState(false);
  const [requiredFieldsValue, setRequiredFieldsValue] = React.useState('');


  function changeValue(e) {
    setRequiredFieldsValue(e.target.value);
  }


  function submit() {
    if (requiredFieldsValue === '') {
      setHasError(true);
    } else {
      setHasError(false);
    }
  }


  function reset() {
    setHasError(false);
    setRequiredFieldsValue('');
  }


  const errorMsg = hasError ? 'Please select a color' : null;


  return (
    <>
      <p>* indicates required fields</p>
      <RadioGroup
        errorMessage={errorMsg}
        required
        labelText="Choose a color *"
        name="requiredFields"
        onChange={changeValue}
        value={requiredFieldsValue}
      >
        <Radio labelText="Red" value="R" />
        <Radio labelText="Blue" value="B" />
        <Radio labelText="Yellow" value="Y" />
      </RadioGroup>
      <br />
      <ButtonGroup>
        <Button onClick={submit}>Submit</Button>
        <Button onClick={reset} color={ButtonColor.secondary}>
          Reset
        </Button>
      </ButtonGroup>
    </>
  );
}

Inverse

The isInverse property is an optional boolean can be applied to the containing RadioGroup, that reverses the colors so that the radio buttons can better appear on a dark background.

import React from 'react';


import { RadioGroup, Radio, Card, CardBody, magma } from 'react-magma-dom';


export function Example() {
  return (
    <>
      <Card isInverse style={{ marginBottom: magma.spaceScale.spacing04 }}>
        <CardBody>
          <RadioGroup
            labelText="Inverse radio buttons"
            id="inverseGroup"
            isInverse
            name="inverse"
            value="selectedOption"
          >
            <Radio id="inverseRadio" labelText="Inverse" value="default" />
            <Radio
              color={magma.colors.success}
              id="successInverseRadio"
              labelText="Success inverse"
              value="success"
            />
            <Radio
              color={magma.colors.danger}
              id="dangerInverseRadio"
              labelText="Danger inverse"
              value="danger"
            />
            <Radio
              disabled
              id="disabledInverseRadio"
              labelText="Disabled inverse"
              value="disabled"
            />
            <Radio
              disabled
              id="disabledInverseRadio"
              labelText="Disabled inverse selected"
              value="selectedOption"
            />
          </RadioGroup>
        </CardBody>
      </Card>


      <Card isInverse>
        <CardBody>
          <p>* indicates required fields</p>
          <RadioGroup
            errorMessage="Please select a color"
            isInverse
            required
            labelText="Inverse with error *"
            name="requiredFieldsInverse"
          >
            <Radio labelText="Option 1" value="R" />
            <Radio labelText="Option2" value="B" />
          </RadioGroup>
        </CardBody>
      </Card>
    </>
  );
}

Custom Styles

Custom styles can be passed into both the RadioGroup component and the Radio component. The containerStyle property will apply to the container. Additional labelStyle and inputStyle properties are available to style the respective elements. Please use discretion when adding custom styles.

import React from 'react';


import { RadioGroup, Radio } from 'react-magma-dom';


export function Example() {
  return (
    <RadioGroup
      style={{ border: '2px solid yellow', padding: '10px' }}
      labelStyle={{ color: 'blue', textTransform: 'uppercase' }}
      labelText="Custom styles"
      id="customGroup"
      name="custom"
    >
      <Radio
        id="custom1"
        containerStyle={{ border: '1px dotted purple' }}
        inputStyle={{ boxShadow: '3px 3px 3px rgba(0, 0 , 0, .6)' }}
        labelStyle={{ color: 'brown', fontStyle: 'italic' }}
        labelText="Custom styles"
        value="1"
      />


      <Radio id="custom2" labelText="No custom styles" value="2" />
    </RadioGroup>
  );
}

Node as labelText

The labelText prop can either be a string, or it can be a React Node.

import React from 'react';


import { RadioGroup, Radio } from 'react-magma-dom';


export function Example() {
  const labelStyles = {
    border: '1px solid #3f3f3f',
    borderRadius: '3px',
    display: 'inline-block',
    padding: '10px',
  };


  const inputStyles = { alignSelf: 'center' };


  return (
    <RadioGroup labelText="Nodes for labels">
      <Radio
        labelText={<span style={labelStyles}>Option 1</span>}
        inputStyle={inputStyles}
        value="1"
      />


      <Radio
        labelText={<span style={labelStyles}>Option 2</span>}
        inputStyle={inputStyles}
        value="2"
      />
    </RadioGroup>
  );
}

Labeling Radio Groups

To meet accessibility requirements, a radio group must have a label. You can provide a label in one of two ways.

You can use the labelText prop, which takes a string. This string will be displayed on screen inside a <label> element and be associated with your radio group.

Or you can use the labelledById prop, which also takes a string. This string should refer to an ID of an element that exists somewhere else on the page. This id will become the value of the aria-labelledby attribute for the group.

import React from 'react';


import { RadioGroup, Radio } from 'react-magma-dom';


export function Example() {
  return (
    <>
      <RadioGroup labelText="Labelled by label" name="labelledByProp">
        <Radio value="1" labelText="Label" />
        <Radio value="2" labelText="Label" />
      </RadioGroup>


      <RadioGroup labelledById="h3Label" name="labelledByChildren">
        <h3 id="h3Label">Labelled by H3</h3>
        <Radio value="3" labelText="Label" />
        <Radio value="4" labelText="Label" />
      </RadioGroup>
    </>
  );
}

Text Position

Use the optional prop textPosition to position the label text on either side of the radio button. The textPosition property takes the values left and right. The default value is right.

import React from 'react';


import { RadioGroup, Radio, RadioTextPosition } from 'react-magma-dom';


export function Example() {
  return (
    <RadioGroup labelText="Text position" name="textPosition">
      <Radio
        labelText="Text left"
        textPosition={RadioTextPosition.left}
        value="1"
      />
      <Radio labelText="Text right" value="1" />
    </RadioGroup>
  );
}

Visually Hidden Label

Adding the isTextVisuallyHidden prop will make the label text for either the radio group or the radio button available to screen readers, but will hide it visually.

Use caution when using the isTextVisuallyHidden prop; it should only be used in rare circumstances when the purpose of the radio button is conveyed in another way. While screen readers will announce the label when the radio button gains focus, it is still best to have a visual label. This is especially helpful for individuals with cognitive disabilities and users who have fine motor control limitations.
import React from 'react';


import { RadioGroup, Radio } from 'react-magma-dom';


export function Example() {
  return (
    <RadioGroup
      labelText="Hidden label"
      id="visuallyHiddenRadioGroup"
      name="visuallyHiddenRadioGroup"
      isTextVisuallyHidden
    >
      <Radio
        value="1"
        id="visuallyHiddenRadio1"
        labelText="Hidden label"
        isTextVisuallyHidden
      />
      <Radio
        value="2"
        id="visuallyHiddenRadio2"
        labelText="Hidden label"
        isTextVisuallyHidden
      />
    </RadioGroup>
  );
}

Forward Ref

Using React's forwardRef feature you can gain access to the reference of the internal radio.

import React from 'react';


import {
  RadioGroup,
  Radio,
  Button,
  ButtonColor,
  ButtonGroup,
} from 'react-magma-dom';


export function Example() {
  const radioRef = React.useRef();
  const [radioGroupVal, setRadioGroupVal] = React.useState(null);


  function handleSelectOne() {
    if (!radioRef.current) {
      setRadioGroupVal(null);
    } else if (radioRef.current.checked) {
      setRadioGroupVal('');
    } else if (!radioRef.current.checked) {
      setRadioGroupVal('1');
    }
  }


  function handleFocusOne() {
    radioRef.current.focus();
  }


  return (
    <>
      <RadioGroup
        labelText="Forward ref usage"
        id="forwardRefGroup"
        name="forwardRef"
        value={radioGroupVal}
      >
        <Radio
          ref={radioRef}
          id="forwardRefRadio1"
          labelText="Option one label"
          value="1"
        />


        <Radio id="forwardRefRadio2" labelText="Option two label" value="2" />
      </RadioGroup>


      <ButtonGroup>
        <Button onClick={handleSelectOne}>Toggle option 1 selection</Button>
        <Button color={ButtonColor.secondary} onClick={handleFocusOne}>
          Focus option 1
        </Button>
      </ButtonGroup>
    </>
  );
}

Testing

Passing in the testId prop will add the data-testid attribute to the wrapper element for RadioGroup and the input element for Radio for easier querying in tests.

<RadioGroup
  labelText="Labelled by label"
  name="labelledByProp"
  testId="radiogroup-id"
>
  <Radio value="1" labelText="Label" testId="radio-1" />
  <Radio value="2" labelText="Label" testId="radio-2" />
</RadioGroup>

Radio Group Props

This component uses forwardRef. The ref is applied to the outer div element.

All of the global HTML attributes can be provided as props and will be applied to the wrapping div element that gets rendered.

children

Required

Description

The content of the component

Type

ReactNode | undefined

Default

-

containerStyle

Description

Style properties for the component container element

Type

CSSProperties

Default

-

errorMessage

Description

Content of the error message. If a value is provided, the radio buttons will be styled to show an error state

Type

React.ReactNode

Default

-

helperMessage

Description

Content of the helper message

Type

React.ReactNode

Default

-

isInverse

Description

If true, the component will have inverse styling to better appear on a dark background

Type

boolean

Default

false

isTextVisuallyHidden

Description

If true, label text for the radio group will be hidden visually, but will still be read by assistive technology

Type

boolean

Default

false

labelStyle

Description

Style properties for the label of the radio group

Type

CSSProperties

Default

-

labelText

Description

Content of label of the radio group; can be node or string. Alternatively, the labelledById prop can be used

Type

React.ReactNode

Default

-

labelledById

Description

ID of the element that labels the radio group, used in the aria-labelledby attribute for the group. Alternatively, the labelText prop can be used

Type

string

Default

-

name

Required

Description

Name attribute the radio group

Type

string

Default

-

onBlur

Description

Action that fires when the radio group loses focus

Type

function

Default

-

onChange

Description

Action that fires when selected value of the radio group changes

Type

function

Default

-

onFocus

Description

Action that fires when one of the radio buttons within the group receives focus

Type

function

Default

-

required

Description

If true, the user must select one radio button for the form to be valid

Type

boolean

Default

false

value

Description

Value of the radio button that is the default selected value for the group

Type

string

Default

-

Radio Props

This component uses forwardRef. The ref is applied to the input element.

All of the standard input attributes can be provided as props and will be applied to the input element that gets rendered.

color

Description

Hex code for the background color

Type

string

Default

theme.colors.primary

containerStyle

Description

Style properties for the component container element

Type

CSSProperties

Default

-

inputStyle

Description

Style properties for the radio button element

Type

CSSProperties

Default

-

isInverse

Description

If true, the component will have inverse styling to better appear on a dark background

Type

boolean

Default

false

isTextVisuallyHidden

Description

If true, label text will be hidden visually, but will still be read by assistive technology

Type

boolean

Default

false

labelStyle

Description

Style properties for the label element

Type

CSSProperties

Default

-

labelText

Required

Description

Content of label; can be node or string

Type

React.ReactNode

Default

-

textPosition

Description

Whether the label appears to the left of the right of the radio button

Type

enum, one of:
RadioTextPosition.left
RadioTextPosition.right

Default

RadioTextPosition.right

On this page

Deploys by Netlify