@primer/react-brand/docs/forms/Radio/react.md

Primer Brand is a GitHub's design system for creating React-based marketing websites and digital experiences.

---
title: Radio
description: Use the radio component when a user needs to select one option from a list.
keywords: ['radio button', 'selection', 'input', 'form', 'option', 'single choice']
source: https://github.com/primer/brand/blob/main/packages/react/src/forms/Radio/Radio.tsx
figma: https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=3063%3A30198&t=QKh20cPDVIFtBCHj-0
storybook: '/react/storybook?path=/story/components-forms-radio--default'
---

## Examples

> **Use [FormControl](../FormControl/index.md) to render a standard radio input field.** If using standalone, it should always be accompanied by a corresponding `<label>` to improve support for assistive technologies.

```jsx
<>
  <Radio value="one" name="radio-group-name" />
  <Radio value="two" name="radio-group-name" />
  <Radio disabled value="three" name="radio-group-name" />
</>
```

> Please use a [Checkbox](../Checkbox/index.md) if the user needs to select more than one option in a list

### Grouping Radio components

Use the `name` prop to group together related `Radio` components in a list.

If you're not building something custom, you should use the [Stack](../../layout/Stack/index.md) and [FormControl](../FormControl/index.md) component to render a group of radio inputs.

#### Using `FormControl`

```jsx
<form>
  <Stack direction={{narrow: 'vertical', regular: 'horizontal'}} gap="condensed" padding="condensed">
    <FormControl>
      <FormControl.Label>Mona</FormControl.Label>
      <Radio name="radio-group" value="mona" />
    </FormControl>
    <FormControl>
      <FormControl.Label>Hubot</FormControl.Label>
      <Radio name="radio-group" value="hubot" />
    </FormControl>
  </Stack>
</form>
```

## Props

### Radio

| Name               | Type                                             |  Default | Description                                                                       |
| :----------------- | :----------------------------------------------- | :------: | :-------------------------------------------------------------------------------- |
| `checked`          | `string`                                         |          | Modifies true/false value of the native radio                                     |
| `className`        | `string`                                         |          | Sets a custom class                                                               |
| `cols`             | `number`                                         |   `30`   | Specifies the visible width of a textarea                                         |
| `defaultChecked`   | `boolean`                                        |          | Selects the radio by default in uncontrolled mode                                 |
| `id`               | `string`                                         |          | Sets a custom id                                                                  |
| `name`             | `string`                                         |          | Required for grouping multiple radios                                             |
| `onChange`         | `(event: React.ChangeEvent) => void`             |          | A callback function that is triggered when the input state has been changed       |
| `ref`              | `React.RefObject`                                |          | Forward a Ref to the underlying DOM node                                          |
| `required`         | `boolean`                                        |          | Indicates to the user and assistive technologies that the field value is required |
| `resize`           | `'both' \| 'horizontal' \| 'vertical' \| 'none'` | `'both'` | Sets whether an element is resizable, and if so, in which directions              |
| `rows`             | `number`                                         |    `7`   | Specifies the visible height of a text area                                       |
| `size`             | `'medium' \| 'large'`                            |          | Provides alternate visual presentation                                            |
| `validationStatus` | `'error' \| 'success'`                           |          | Applies visual and semantic state to the underlying elements                      |
| `value`            | `string`                                         |          | A unique value that is never shown to the user                                    |

Additional props can be passed to the `<input>` element. [See MDN for a list of props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) accepted by the `<input>` element.