RadioGroup

Radio groups allow users to select a single option from a list of mutually exclusive options. All possible options are exposed up front for users to compare.

import {RadioGroup, Radio} from '@react-spectrum/s2';

<RadioGroup label="Favorite pet">
  <Radio value="cats">Cat</Radio>
  <Radio value="dogs">Dog</Radio>
  <Radio value="dragon">Dragon</Radio>
</RadioGroup>

Value

Use the value or defaultValue prop to set the selected item, and onChange to handle selection changes.

import {RadioGroup, Radio} from '@react-spectrum/s2';
import {useState} from 'react';

function Example() {
  let [selected, setSelected] = useState(null);

  return (
    <>
      <RadioGroup
        label="Favorite sport"
        value={selected}
        onChange={setSelected}>
        <Radio value="soccer">Soccer</Radio>
        <Radio value="baseball">Baseball</Radio>
        <Radio value="basketball">Basketball</Radio>
      </RadioGroup>
      <p>Current selection: {selected || 'None'}</p>
    </>
  );
}

Forms

Use the name prop to submit the selected radio to the server. Set the isRequired prop to validate that the user selects an option, or implement custom client or server-side validation. See the Forms guide to learn more.

import {RadioGroup, Radio, Button, Form} from '@react-spectrum/s2';

function Example(props) {
  return (
    <Form>
      <RadioGroup
        {...props}
        label="Favorite pet"
        name="pet"
        isRequired
      >
        <Radio value="dog">Dog</Radio>
        <Radio value="cat">Cat</Radio>
        <Radio value="dragon">Dragon</Radio>
      </RadioGroup>
      <Button type="submit">Submit</Button>
    </Form>
  );
}

API

<RadioGroup>
  <Radio />
</RadioGroup>

RadioGroup

Radio

Testing

Test utils

@react-spectrum/test-utils offers common radio group interaction utilities which you may find helpful when writing tests. To install, simply add it to your dev dependencies via your preferred package manager.

yarn add @react-spectrum/test-utils --dev

Once installed, you can access the User that @react-spectrum/test-utils provides in your test file as shown below. This user only needs to be initialized once and then can be used to generate the RadioGroup tester in your test cases. This gives you access to RadioGroup specific utilities that you can then call within your test to query for specific subcomponents or simulate common interactions. The example test case below shows how you might go about setting up the RadioGroup tester, use it to changing radio selection, and verify the radio group's state after each interaction.

// RadioGroup.test.ts
import {render} from '@testing-library/react';
import {User} from '@react-spectrum/test-utils';

let testUtilUser = new User({interactionType: 'mouse', advanceTimer: jest.advanceTimersByTime});
// ...

it('RadioGroup can switch the selected radio', async function () {
  // Render your test component/app and initialize the radiogroup tester
  let {getByRole} = render(
    <RadioGroup>
      ...
    </RadioGroup>
  );

  let radioGroupTester = testUtilUser.createTester('RadioGroup', {root: getByRole('radiogroup')});
  let radios = radioGroupTester.radios;
  expect(radioGroupTester.selectedRadio).toBeFalsy();

  await radioGroupTester.triggerRadio({radio: radios[0]});
  expect(radioGroupTester.selectedRadio).toBe(radios[0]);

  await radioGroupTester.triggerRadio({radio: radios[1]});
  expect(radioGroupTester.selectedRadio).toBe(radios[1]);
});

See below for the full definition of the User and the RadioGroup tester.

Properties

Methods

Properties

Methods

Testing FAQ