RadioGroupField

RadioGroupField allows users to select a single option from a list of mutually exclusive options.

ARIA pattern Theme source React source Feedback

Demo

Usage

Import the Radio and RadioGroupField components, and nest the Radio options inside the RadioGroupField.

RadioGroupField requires both legend and name for accessibility and form submission, respectively. Radio only requires the value prop, which will be submitted with form data.

You also have the option to set a Radio as pre-selected by passing its value to the defaultValue prop on the RadioGroupField.

DogCatBird

import { Radio, RadioGroupField } from '@aws-amplify/ui-react';

export const BasicExample = () => (
  <RadioGroupField legend="Animal" name="animal" defaultValue="Dog">
    <Radio value="Dog">Dog</Radio>
    <Radio value="Cat">Cat</Radio>
    <Radio value="Bird">Bird</Radio>
  </RadioGroupField>
);

Controlled component

To manually control the RadioGroupField state, you can use the value and onChange props.

🍎🍌🥕

import * as React from 'react';
import { Radio, RadioGroupField } from '@aws-amplify/ui-react';

export const ControlledExample = () => {
  const [value, setValue] = React.useState('apple');

  return (
    <RadioGroupField
      legend="Fruit"
      name="fruit"
      value={value}
      onChange={(e) => setValue(e.target.value)}
    >
      <Radio value="apple">🍎</Radio>
      <Radio value="banana">🍌</Radio>
      <Radio value="carrot">🥕</Radio>
    </RadioGroupField>
  );
};

Sizes

Use the size prop to change the RadioGroupField size. Available options are small, large, and none (default).

Small

Default

Large

import { Radio, RadioGroupField } from '@aws-amplify/ui-react';

export const SizeExample = () => (
  <>
    <RadioGroupField legend="small" name="small" size="small" legendHidden>
      <Radio value="small">Small</Radio>
    </RadioGroupField>
    <RadioGroupField legend="default" name="default" legendHidden>
      <Radio value="default">Default</Radio>
    </RadioGroupField>
    <RadioGroupField legend="large" name="large" size="large" legendHidden>
      <Radio value="large">Large</Radio>
    </RadioGroupField>
  </>
);

Direction

Use the direction prop to change the RadioGroupField direction. Available options are row and column (default).

TopToBottom

LeftToRight

import { Radio, RadioGroupField } from '@aws-amplify/ui-react';

export const DirectionExample = () => (
  <>
    <RadioGroupField legend="Column" name="column">
      <Radio value="top">Top</Radio>
      <Radio value="to-column">To</Radio>
      <Radio value="bottom">Bottom</Radio>
    </RadioGroupField>
    <RadioGroupField legend="Row" name="row" direction="row">
      <Radio value="left">Left</Radio>
      <Radio value="to-row">To</Radio>
      <Radio value="right">Right</Radio>
    </RadioGroupField>
  </>
);

Label position

Use the labelPosition prop to control where the label is in relation to the Radio. You may pass labelPosition to either the RadioGroupField or individual Radios.

Default

Start

Top

Bottom

import { Radio, RadioGroupField, Flex } from '@aws-amplify/ui-react';

export const LabelPositionExample = () => (
  <Flex>
    <RadioGroupField legend="Default" name="default" legendHidden>
      <Radio value="default">Default</Radio>
    </RadioGroupField>

    <RadioGroupField
      legend="Start"
      name="start"
      labelPosition="start"
      legendHidden
    >
      <Radio value="start">Start</Radio>
    </RadioGroupField>

    <RadioGroupField legend="Top" name="top" labelPosition="top" legendHidden>
      <Radio value="top">Top</Radio>
    </RadioGroupField>

    <RadioGroupField
      legend="Bottom"
      name="bottom"
      labelPosition="bottom"
      legendHidden
    >
      <Radio value="bottom">Bottom</Radio>
    </RadioGroupField>
  </Flex>
);

State

The available RadioGroupField states include isDisabled and isReadOnly. A disabled field will be not be focusable not mutable and will not be submitted with form data. A readonly field cannot be edited by the user, but will be submitted with form data.

Disabled radios and radio group

Option 1Option 2 is disabledOption 3

AllOptionsDisabled

import { Radio, RadioGroupField } from '@aws-amplify/ui-react';

export const DisabledExample = () => (
  <>
    <RadioGroupField legend="Disabled Radio" name="disabled-radio">
      <Radio value="option-1">Option 1</Radio>
      <Radio value="option-2" isDisabled>
        Option 2 is disabled
      </Radio>
      <Radio value="option-3">Option 3</Radio>
    </RadioGroupField>

    <RadioGroupField
      legend="Disabled RadioGroupField"
      name="disabled-field"
      isDisabled
    >
      <Radio value="all">All</Radio>
      <Radio value="options">Options</Radio>
      <Radio value="disabled">Disabled</Radio>
    </RadioGroupField>
  </>
);

Read-only radio group

I love Amplify UI 😍I like Amplify UI 👍I appreciate Amplify UI 🙏

import { Radio, RadioGroupField } from '@aws-amplify/ui-react';

export const ReadOnlyExample = () => (
  <RadioGroupField
    legend="Read-only"
    name="read-only"
    defaultValue="love"
    isReadOnly
  >
    <Radio value="love">I love Amplify UI 😍</Radio>
    <Radio value="like">I like Amplify UI 👍</Radio>
    <Radio value="appreciate">I appreciate Amplify UI 🙏</Radio>
  </RadioGroupField>
);

Validation error

Use the hasError and errorMessage props to mark a RadioGroupField as having a validation error.

HTMLCSSJavaScript

This is a required field. Please select an option.

import * as React from 'react';
import { Radio, RadioGroupField } from '@aws-amplify/ui-react';

const options = ['HTML', 'CSS', 'JavaScript'];

export const ErrorExample = () => {
  const [language, setLanguage] = React.useState(null);

  return (
    <RadioGroupField
      legend="Language"
      name="example-12"
      onChange={(e) => setLanguage(e.target.value)}
      errorMessage="This is a required field. Please select an option."
      hasError={!language}
      legendHidden
    >
      {options.map((option) => (
        <Radio key={option} value={option}>
          {option}
        </Radio>
      ))}
    </RadioGroupField>
  );
};

Accessibility

An HTML <legend> element is automatically associated with the RadioGroupField's <fieldset> via the legend prop so that the radiogroup is accessibly labelled. For Radio, a <label> element will be automatically generated via the label prop. Both can accept a string or ReactNode.

If no id is provided to <Radio>, one will be automatically generated and connected to both the label and the form control; in this case the input[type="radio"].

How can I visually hide the legend or labels while maintaining accessibility?

In some applications it may be desirable to hide the legend when the field purpose is visually apparent such as a search field with button. The legendHidden prop can be used on RadioGroupField to visually hide the <legend> while still keeping it available to screenreaders. Similarily, the labelHidden prop can be used to accessibly hide a <Radio> element's <label>

UX Tip: refrain hiding legends and labels if doing so hides important information needed by the user to fill out the field.

CSS Styling

Theme

You can customize the appearance of all RadioGroupField components in your application with a Theme.

RadioGroupField Theme Source

BlueNavyCerulean

import { Radio, RadioGroupField, ThemeProvider } from '@aws-amplify/ui-react';

const theme = {
  name: 'radiogroup-theme',
  tokens: {
    components: {
      radiogroup: {
        radio: {
          borderWidth: { value: '{borderWidths.small}' },
          borderColor: { value: '{colors.blue.60}' },
          backgroundColor: { value: '{colors.blue.20}' },
          _checked: {
            color: { value: '{colors.blue.80}' },
          },
          label: {
            color: { value: '{colors.blue.80}' },
          },
        },
        legend: {
          color: { value: '{colors.blue.80}' },
          fontWeight: { value: '{fontWeights.bold}' },
        },
      },
    },
  },
};

export const RadioGroupFieldThemeExample = () => (
  <ThemeProvider theme={theme} colorMode="light">
    <RadioGroupField legend="Themed example" name="themed" defaultValue="blue">
      <Radio value="blue">Blue</Radio>
      <Radio value="navy">Navy</Radio>
      <Radio value="cerulean">Cerulean</Radio>
    </RadioGroupField>
  </ThemeProvider>
);

Target classes

Class	Description
`amplify-radio`	Top level element that wraps the Radio primitive
`amplify-radio__button`	Class applied to the displayed radio button
`amplify-radio__input`	Class applied to the visually hidden radio input
`amplify-radio__label`	Class applied to the radio label
`amplify-radiogroupfield`	Top level element that wraps the RadioGroupField primitive
`amplify-radiogroup`	Class applied to the radio group wrapper

No variables available for this component

Global styling

To override styling on all Radio buttons, you can set the Amplify CSS variables or use the built-in .amplify-radio__button class.

/* styles.css */
[data-amplify-theme] {
  --amplify-components-radio-button-background-color: green;
  --amplify-components-radio-button-border-color: lightgreen;
}
/* OR */
.amplify-radio__button {
  background-color: green;
  border-color: lightgreen;
}

To replace Radio button styling, unset it:

.amplify-radio__button {
  all: unset;
  /* Add your styling here*/
}

Local styling

To override styling on a specific Radio, you can use (in order of increasing specificity): a class selector, data attributes, or style props.

Using a class selector:

Red

Orange

Yellow

/* styles.css */
.custom-radio .amplify-radio__input:checked + .amplify-radio__button {
  background-color: orange;
  border-color: red;
  color: yellow;
}

import { Radio, RadioGroupField } from '@aws-amplify/ui-react';

<RadioGroupField legend="Language" name="language" defaultValue="html">
  <Radio value="html" className="custom-radio">
    html
  </Radio>
</RadioGroupField>;

Using data attributes:

/* styles.css */

/* Override only large size styles */
.amplify-radiogroupfield[data-size='large'] {
  font-size: 1.25rem;
}