## Usage

Use the `<Radio />` component when the user needs to choose a single option from a group of options. The radio will automatically render a visibly hidden `<input type="radio">` to ensure events propagate correctly.

```tsx live
<Flex flexDirection="column" gap="small">
  <Radio name="example-form">Blue</Radio>
  <Radio name="example-form">Red</Radio>
</Flex>
```

### Guidelines

- In a "create"-form (new data being entered), no radio elements should be checked initially
- Prefer placing the radios underneath each other to aid scannability
- Always utilise at least two or more choices
- List radios in a logical order, e.g:
  - Alphabetically
  - Numerically
  - Time-based
  - Most to least likely to be checked
- Each option should be independent from every other option

## Controlled

The radio can be uncontrolled or controlled. Use the `checked` prop, along with `onChange` to take control of the state. In most cases, [React recommends using controlled components](https://reactjs.org/docs/uncontrolled-components.html) to implement forms.

Tip: Wrap your radios with the [RadioGroup](#radio-group) component to manage the state more easily, and get the recommended layout out of the box.

```tsx live
const [checked, setChecked] = useState('');
const setCheckedByKey = (key: string) => () => setChecked(key);
const isChecked = (key: string) => key === checked;

return (
  <Flex as="form" flexDirection="column" gap="small">
    <Radio checked={isChecked('1')} onChange={setCheckedByKey('1')}>
      Radio 1
    </Radio>
    <Radio checked={isChecked('2')} onChange={setCheckedByKey('2')}>
      Radio 2
    </Radio>
  </Flex>
);
```

## Disabled

```tsx live
<Flex as="form" flexDirection="column" gap="small">
  <Radio disabled>Disabled</Radio>
  <Radio checked disabled>
    Checked + disabled
  </Radio>
</Flex>
```

## Size

There are two radio sizes, `small` and `medium` (default).

```tsx live
<Flex as="form" flexDirection="column" gap="small">
  <Radio size="small">Small radio</Radio>
  <Radio>Medium radio (default)</Radio>
</Flex>
```

## Custom children

To customise or add more information to the radio label, you can pass in any other component via `children`.

```tsx live
<Flex as="form">
  <Radio>
    <Flex flexDirection="column">
      <Text fontWeight="bold">Bold label</Text>
      <Text fontSize="xsmall" color="neutralSubtle">
        Sub text
      </Text>
    </Flex>
  </Radio>
</Flex>
```

## Build a custom radio

In rare cases when you need to create a custom radio, you can use the `<RadioPrimitive />` component. Don't forget to use a `<label>` in conjunction, with a `htmlFor="RADIO_PRIMITIVE_ID_HERE"` for accessibility.

```tsx live
const [checked, setChecked] = useState('');
const setCheckedByKey = (key: string) => () => setChecked(key);
const isChecked = (key: string) => key === checked;

return (
  <Flex as="form" flexDirection="column" gap="medium">
    <Flex
      as="label"
      htmlFor="custom-radio-1"
      backgroundColor={isChecked('1') ? 'informativeSubtle' : 'neutralSubtle'}
      alignItems="center"
      padding="medium"
      borderRadius="medium"
      gap="medium"
    >
      <RadioPrimitive id="custom-radio-1" checked={isChecked('1')} onChange={setCheckedByKey('1')} />
      <Text>
        <Text fontWeight="bold">1:</Text> This is a custom component using the RadioPrimitive
      </Text>
    </Flex>

    <Flex
      as="label"
      htmlFor="custom-radio-2"
      backgroundColor={isChecked('2') ? 'informativeSubtle' : 'neutralSubtle'}
      alignItems="center"
      padding="medium"
      borderRadius="medium"
      gap="medium"
    >
      <RadioPrimitive id="custom-radio-2" checked={isChecked('2')} onChange={setCheckedByKey('2')} />
      <Text>
        <Text fontWeight="bold">2:</Text> This is a custom component using the RadioPrimitive
      </Text>
    </Flex>
  </Flex>
);
```

## Radio group

The `<RadioGroup />` component is a styled context provider to help manage the state of a controlled group of radios, using the React Context API. Each `<Radio />` **must** have a unique `value` set.

It is recommended to wrap your radio group with a [Fieldset](/packages/fieldset/), which lets you add a legend and will be read out as a "group" by some screen readers.

```tsx live
const [checkedValue, setCheckedValue] = useState('blue');

return (
  <form>
    <Flex flexDirection="column" gap="medium">
      <Fieldset legend="Your favourite colour" legendStyle="group">
        <RadioGroup value={checkedValue} onInputChange={setCheckedValue}>
          <Radio value="blue">Blue</Radio>
          <Radio value="red">Red</Radio>
          <Radio value="white">White</Radio>
        </RadioGroup>
      </Fieldset>

      <Divider />

      <Text fontFamily="mono">checkedValue: {checkedValue}</Text>
    </Flex>
  </form>
);
```

### Size

Use the `size` prop to control the input size of the nested radios of the radio group.

```tsx live
const [checkedValue, setCheckedValue] = useState('blue');

return (
  <form>
    <RadioGroup size="small" value={checkedValue} onInputChange={setCheckedValue}>
      <Radio value="blue">Blue</Radio>
      <Radio value="red">Red</Radio>
      <Radio value="white">White</Radio>
    </RadioGroup>
  </form>
);
```

### Horizontal

In rare cases you can add the `horizontal` prop to make the radios in the radio group stack horizontally. However – it's recommended to use the default vertical layout for the best readability and experience.

```tsx live
const [checkedValue, setCheckedValue] = useState('blue');

return (
  <form>
    <RadioGroup horizontal value={checkedValue} onInputChange={setCheckedValue}>
      <Radio value="blue">Blue</Radio>
      <Radio value="red">Red</Radio>
      <Radio value="white">White</Radio>
    </RadioGroup>
  </form>
);
```

### Validation

If you need validation on a radio group you can use the same validation props as [Field](/packages/field/); `invalid` and `message`.

```tsx live
<RadioGroup
  invalid={true}
  message="At least one is required"
  value=""
  onInputChange={() => {
    return;
  }}
>
  <Radio value="apple">Apple</Radio>
  <Radio value="banana">Banana</Radio>
  <Radio value="orange">Orange</Radio>
</RadioGroup>
```

### Required

Radio groups inherit the `required` state from a parent [Fieldset](/packages/fieldset/).

```tsx live
<Fieldset required legend="Required choice" legendStyle="group">
  <RadioGroup
    value=""
    onInputChange={() => {
      return;
    }}
  >
    <Radio value="apple">Apple</Radio>
    <Radio value="banana">Banana</Radio>
    <Radio value="orange">Orange</Radio>
  </RadioGroup>
</Fieldset>
```

### Keep space for message

Just like the [Field](/packages/field/), extra vertical space is added under each radio group by default. This prevents layout shifts when a validation message is displayed. You can turn this extra space off by setting `keepSpaceForMessage` to `false`.

A control that allows the user to select a single value from multiple options.

Radio

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AddressInput

AppLayout

Avatar

Badge

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Checkbox

Core

DateDropdown

DateInput

Divider

EmptyState

Field

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Modal

Notice

PageHeader

Pagination

PhoneInput

Popover

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Toggle

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources