> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: RadioGroup Component

## Article: RadioGroup Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/form/radio-group-component.md

## Article Content:

# RadioGroup

_Components/Form_

Interactive docs page: <https://wix-pages.com/design-system-documentation/#/component/radiogroup>

## Overview

```jsx
() => {
  const [value, setValue] = React.useState(1);

  return (
    <Box align="center">
      <FormField label="Choose a size" stretchContent={false}>
        <RadioGroup
          onChange={(newValue) => setValue(Number(newValue))}
          value={value}
        >
          <RadioGroup.Radio value={1}>Small</RadioGroup.Radio>
          <RadioGroup.Radio value={2}>Medium</RadioGroup.Radio>
          <RadioGroup.Radio value={3}>Large</RadioGroup.Radio>
        </RadioGroup>
      </FormField>
    </Box>
  );
};
```

Radio groups (radio buttons) allow users to choose a single item from a list of options.

### Do

- Allow the user to select a single item from a short list of 2 to 5 options.
- Use it to show all available options.
- Have a preselected option where possible, or add a neutral option, such as "None" or "All".

### Don't

- Don't use it when multiple options can be selected. Use the `<Checkbox/>` component instead.
- Don't use it for lists of more than 5 options. Use the `<Dropdown/>` or `<Autocomplete/>` components instead.

### Feature examples

#### Structure

The component consists of a list of options with radio buttons wrapped inside `<RadioGroup>`.

Option labels are plain text by default, but they can be replaced with any other component or set of components.

```jsx
<RadioGroup value={1}>
  <RadioGroup.Radio value={1}>Option 1</RadioGroup.Radio>
  <RadioGroup.Radio value={2}>Option 2</RadioGroup.Radio>
  <RadioGroup.Radio value={3}>Option 3</RadioGroup.Radio>
  <RadioGroup.Radio value={4}>Option 4</RadioGroup.Radio>
</RadioGroup>;
```

#### Size

Adjust the component size using the size prop. It supports 2 sizes:

`medium` (default) - use in all common cases

`small` - use in more dense layouts

```jsx
<StorybookComponents.Stack flexDirection="column">
  <RadioGroup size="medium" value={1}>
    <RadioGroup.Radio value={1}>Option 1</RadioGroup.Radio>
    <RadioGroup.Radio value={2}>Option 2</RadioGroup.Radio>
    <RadioGroup.Radio value={3}>Option 3</RadioGroup.Radio>
  </RadioGroup>
  <RadioGroup size="small" value={1}>
    <RadioGroup.Radio value={1}>Option 1</RadioGroup.Radio>
    <RadioGroup.Radio value={2}>Option 2</RadioGroup.Radio>
    <RadioGroup.Radio value={3}>Option 3</RadioGroup.Radio>
  </RadioGroup>
</StorybookComponents.Stack>;
```

#### Layout

Control the layout of the options with the `display` prop. Choose from 2 layouts:

- For most common cases, use the default `vertical`.
- Use `horizontal` for options with short labels (e.g., Yes/No selections in a form), or when there is limited space.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <RadioGroup value={1} display="vertical">
    <RadioGroup.Radio value={1}>Vertical 1</RadioGroup.Radio>
    <RadioGroup.Radio value={2}>Vertical 2</RadioGroup.Radio>
    <RadioGroup.Radio value={3}>Vertical 3</RadioGroup.Radio>
  </RadioGroup>
  <RadioGroup value={1} display="horizontal">
    <RadioGroup.Radio value={1}>Horizontal 1</RadioGroup.Radio>
    <RadioGroup.Radio value={2}>Horizontal 2</RadioGroup.Radio>
    <RadioGroup.Radio value={3}>Horizontal 3</RadioGroup.Radio>
  </RadioGroup>
</StorybookComponents.Stack>;
```

#### Spacing

Control the pixel spacing between options with the `spacing` prop.

```jsx
<StorybookComponents.Stack gap="72px">
  <RadioGroup spacing="12px">
    <RadioGroup.Radio value={1}>Option 1</RadioGroup.Radio>
    <RadioGroup.Radio value={2}>Option 2</RadioGroup.Radio>
    <RadioGroup.Radio value={3}>Option 3</RadioGroup.Radio>
  </RadioGroup>
  <RadioGroup spacing="18px">
    <RadioGroup.Radio value={1}>Option 1</RadioGroup.Radio>
    <RadioGroup.Radio value={2}>Option 2</RadioGroup.Radio>
    <RadioGroup.Radio value={3}>Option 3</RadioGroup.Radio>
  </RadioGroup>
  <RadioGroup spacing="24px">
    <RadioGroup.Radio value={1}>Option 1</RadioGroup.Radio>
    <RadioGroup.Radio value={2}>Option 2</RadioGroup.Radio>
    <RadioGroup.Radio value={3}>Option 3</RadioGroup.Radio>
  </RadioGroup>
</StorybookComponents.Stack>;
```

#### Button alignment

Control how the radio buttons align to the text with the `vAlign` prop. Choose from 2 alignments:

- `center` (the default) aligns the radio button to the middle of the text. It is recommended for most common cases.
- `top` aligns the radio buttons to the top of the text. This is good for options that go over 3 or more lines of text.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <RadioGroup vAlign="center">
    <RadioGroup.Radio>
      <Heading size="small">Center aligned radio</Heading>
      <Text secondary size="small">
        Subtitle
      </Text>
    </RadioGroup.Radio>
  </RadioGroup>
  <RadioGroup vAlign="top">
    <RadioGroup.Radio>
      <Heading size="small">Top aligned radio</Heading>
      <Text secondary size="small">
        Subtitle
      </Text>
    </RadioGroup.Radio>
  </RadioGroup>
</StorybookComponents.Stack>;
```

#### Disabled buttons

Radio options can be disabled in 2 ways:

- Disable all options at once with `disabled`.
- Choose which options to disable with `disabledRadios`.

```jsx
<StorybookComponents.Stack gap="60px">
  <RadioGroup disabled value={1}>
    <RadioGroup.Radio value={1}>All disabled</RadioGroup.Radio>
    <RadioGroup.Radio value={2}>All disabled</RadioGroup.Radio>
    <RadioGroup.Radio value={3}>All disabled</RadioGroup.Radio>
  </RadioGroup>
  <RadioGroup disabledRadios={[3]} value={1}>
    <RadioGroup.Radio value={1}>Selected</RadioGroup.Radio>
    <RadioGroup.Radio value={2}>Unselected</RadioGroup.Radio>
    <RadioGroup.Radio value={3}>Disabled</RadioGroup.Radio>
  </RadioGroup>
</StorybookComponents.Stack>;
```

#### Status message

Add text that explains the status or what action the user should take with the `statusMessage` prop.

Show the status message inline, directly below the radio group by wrapping it in a `<FormField/>` and adding `statusMessage`.

View more inline status message examples in `<FormField/>`.

```jsx
<FormField status="error" statusMessage="This is an error message.">
  <RadioGroup>
    <RadioGroup.Radio value={1}>Option 1</RadioGroup.Radio>
    <RadioGroup.Radio value={2}>Option 2</RadioGroup.Radio>
    <RadioGroup.Radio value={3}>Option 3</RadioGroup.Radio>
  </RadioGroup>
</FormField>;
```

#### Button area

Highlight the clickable area of an option by controlling the design. It's recommended to always use this on mobile.

- Specify when the button area should be highlighted (on hover, always, or not at all) with `selectionArea`.
- To choose a filled or outlined design, use `selectionAreaSkin`.
- Define the white pixel spacing around each radio button with `selectionAreaPadding`.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <RadioGroup
    value={1}
    selectionArea="always"
    selectionAreaSkin="outlined"
    selectionAreaPadding="12px 18px"
  >
    <RadioGroup.Radio value={1}>Option 1</RadioGroup.Radio>
    <RadioGroup.Radio value={2}>Option 2</RadioGroup.Radio>
    <RadioGroup.Radio value={3}>Option 3</RadioGroup.Radio>
  </RadioGroup>
  <RadioGroup
    value={1}
    selectionArea="hover"
    selectionAreaSkin="filled"
    selectionAreaPadding="12px 18px"
  >
    <RadioGroup.Radio value={1}>Option 1</RadioGroup.Radio>
    <RadioGroup.Radio value={2}>Option 2</RadioGroup.Radio>
    <RadioGroup.Radio value={3}>Option 3</RadioGroup.Radio>
  </RadioGroup>
</StorybookComponents.Stack>;
```

#### Additional content

Use the `content` prop to show additional details for an option. It accepts any kind of content and places it outside of a radio option.

```jsx
<RadioGroup value={1} selectionArea="always">
  <RadioGroup.Radio
    value={1}
    content={
      <StorybookComponents.Placeholder margin={2}>
        Details about Option 1
      </StorybookComponents.Placeholder>
    }
  >
    Option 1
  </RadioGroup.Radio>
  <RadioGroup.Radio
    value={2}
    content={
      <StorybookComponents.Placeholder margin={2}>
        Details about Option 2
      </StorybookComponents.Placeholder>
    }
  >
    Option 2
  </RadioGroup.Radio>
</RadioGroup>;
```

### Common use case examples

#### Settings panel

Only use small size radio buttons in settings panels to ensure consistency across all panels.

```jsx
() => {
  const [defaultStateselected, setDefaultStateSelected] = React.useState(1);
  const [homepageTypeSelected, setHomepageTypeSelected] = React.useState(1);

  return (
    <SidePanel maxHeight="576px" width="288px" skin="floating">
      <SidePanel.Header title="Breadcrumbs Settings" />
      <SidePanel.Content noPadding>
        <SidePanel.Field>
          <FormField label="Default state">
            <RadioGroup
              value={defaultStateselected}
              onChange={(newValue) => setDefaultStateSelected(Number(newValue))}
              size="small"
            >
              <RadioGroup.Radio value={1}>Full trail</RadioGroup.Radio>
              <RadioGroup.Radio value={2}>Hide homepage</RadioGroup.Radio>
              <RadioGroup.Radio value={3}>Hide current page</RadioGroup.Radio>
            </RadioGroup>
          </FormField>
        </SidePanel.Field>
        <SidePanel.Field>
          <FormField label="Display homepage as">
            <RadioGroup
              value={homepageTypeSelected}
              onChange={(newValue) => setHomepageTypeSelected(Number(newValue))}
              size="small"
            >
              <RadioGroup.Radio value={1}>Text</RadioGroup.Radio>
              <RadioGroup.Radio value={2}>Icon</RadioGroup.Radio>
            </RadioGroup>
          </FormField>
        </SidePanel.Field>
      </SidePanel.Content>
    </SidePanel>
  );
};
```

#### Default selection

Have a default option selected whenever possible, ideally a neutral choice such as "None" or "All".

```jsx
() => {
  const [selected, setSelected] = React.useState(1);

  return (
    <RadioGroup
      value={selected}
      onChange={(newValue) => setSelected(Number(newValue))}
    >
      <RadioGroup.Radio value={1}>All</RadioGroup.Radio>
      <RadioGroup.Radio value={2}>In stock</RadioGroup.Radio>
      <RadioGroup.Radio value={3}>Out of stock</RadioGroup.Radio>
    </RadioGroup>
  );
};
```

#### Additional info

Use `<InfoIcon/>` to add a tooltip next to an option to provide additional information.

```jsx
() => {
  const [selected, setSelected] = React.useState(2);

  return (
    <FormField label="How would you like to add tax?">
      <RadioGroup
        value={selected}
        onChange={(newValue) => setSelected(Number(newValue))}
      >
        <RadioGroup.Radio value={1}>Include in the price</RadioGroup.Radio>
        <RadioGroup.Radio value={2}>
          Add at checkout
          <Box inline>
            <InfoIcon content="Tax will not be included in the price of your plans. Customers will see the tax added on at checkout." />
          </Box>
        </RadioGroup.Radio>
      </RadioGroup>
    </FormField>
  );
};
```

#### Horizontal layout

Use a horizontal layout when displaying radio lists with 2-3 options and short descriptions. This layout is great for situations where vertical space is limited.

```jsx
() => {
  const [selected, setSelected] = React.useState(2);
  return (
    <CustomModalLayout
      title="Add an area for local delivery"
      subtitle="Set a delivery area within a radius or certain postal codes."
      primaryButtonText="Add Area"
      secondaryButtonText="Cancel"
      onCloseButtonClick={() => {}}
    >
      <Layout cols={1}>
        <FormField label="Area name">
          <Input placeholder="e.g., Lower East Side" />
        </FormField>
        <FormField label="Set area by">
          <RadioGroup
            display="horizontal"
            value={selected}
            onChange={(newValue) => setSelected(Number(newValue))}
          >
            <RadioGroup.Radio value={1}>Radius</RadioGroup.Radio>
            <RadioGroup.Radio value={2}>Postal codes</RadioGroup.Radio>
          </RadioGroup>
        </FormField>
        <FormField label="Add postal codes that all have the same delivery rate">
          <InputArea placeholder="Separate postal codes with commas, e.g., 10002, 10003, 10009" />
        </FormField>
      </Layout>
    </CustomModalLayout>
  );
};
```

#### Custom button

Other components can also be used in radio option labels (e.g., avatar, illustration, additional text).

```jsx
() => {
  const [selected, setSelected] = React.useState(1);
  return (
    <Card>
      <Card.Header
        title="Business type"
        subtitle="Define your business type for legal purposes."
      />
      <Card.Divider />
      <Card.Content>
        <RadioGroup
          selectionArea="always"
          selectionAreaSkin="outlined"
          selectionAreaPadding="18px"
          spacing="12px"
          value={selected}
          onChange={(newValue) => setSelected(Number(newValue))}
        >
          <RadioGroup.Radio value={1}>
            <Box gap={2} verticalAlign="middle">
              <Avatar />
              <Box direction="vertical">
                <Text weight="normal">Individual</Text>
                <Text size="small">
                  You own and run the business with a personal bank account.
                </Text>
              </Box>
            </Box>
          </RadioGroup.Radio>
          <RadioGroup.Radio value={2}>
            <Box gap={2} verticalAlign="middle">
              <Avatar shape="square" />
              <Box direction="vertical">
                <Text weight="normal">Partnership, LLC or Corporation</Text>
                <Text size="small">
                  You have a business registration number and a business bank
                  account.
                </Text>
              </Box>
            </Box>
          </RadioGroup.Radio>
        </RadioGroup>
      </Card.Content>
    </Card>
  );
};
```

## Code

```jsx
import { RadioGroup } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | Lists RadioGroup items. You're recommended to use it with <RadioGroup.Radio/>. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `disabled` | `boolean` | — | Disables the entire group. |
| `disabledRadios` | `(string \| number \| undefined)[]` | — | Specify the values of the disabled radio buttons. |
| `display` | `"horizontal" \| "vertical"` | `'vertical'` | Control options direction. |
| `fullWidth` | `boolean` | `false` | Makes component full width and divides all available horizontal space into even parts for each radio button. |
| `name` | `string` | — | Sets a unique name of a radio group. |
| `onChange` | `(value: string \| number \| undefined) => void` | — | Defines a callback function which is called every time user selects a different value. |
| `selectionArea` | `"none" \| "hover" \| "always"` | `'none'` | Controls selection area highlight visibility. |
| `selectionAreaPadding` | `string \| number \| string & {}` | — | Sets the amount of white space around the radio label in pixels. |
| `selectionAreaSkin` | `"filled" \| "outlined"` | `'filled'` | Sets the design of the selection area. |
| `size` | `"small" \| "medium"` | `'medium'` | Controls size. |
| `spacing` | `string` | — | Controls the distance between options. |
| `type` | `"button" \| "default"` | — | Controls whether the group renders standard radios or radio buttons. |
| `vAlign` | `"center" \| "top"` | `'center'` | Controls radio alignment to the label on Y axis. |
| `value` | `string \| number` | `''` | Specifies the selected radio value. |

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { RadioGroupUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { RadioGroupTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { RadioGroupTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { RadioGroupTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `selectByValue` | Selects the radio that matches the provided value |
| `selectByIndex` | Selects the radio in the provided index |
| `getRadioValueAt` | Get the radio value in the provided index |
| `getRadioAtIndex` | Get the radio element in the provided index, returns an element merged with the RadioButton driver methods |
| `getSelectedValue` | Get the value of the selected radio |
| `isRadioDisabled` | Checks if the radio in the provided index is disabled |
| `getNumberOfRadios` | Get the number of rendered radios |
| `getRadioIdAt` | Get the value of radio button id at the provided index |
| `getRadioName` | Get the value of radio button name at the provided index |
| `isRadioChecked` | Checks if the radio with the provided index is checked |
| `exists` | Checks whether the component found with the given data hook. |
| `element` | Gets the component root element. |
| `click` | Clicks on the component root element. |
| `base` | Returns UniDriver for the base element. |

## Changelog

- **1.340.0** (2026-10-21) — maintenance release, no component-specific changes
- **1.339.0** (2026-10-19) — maintenance release, no component-specific changes
- **1.338.0** (2026-10-15) — maintenance release, no component-specific changes
- **1.330.0** (2026-09-28) — maintenance release, no component-specific changes
- **1.329.0** (2026-09-24) — maintenance release, no component-specific changes
- **1.328.0** (2026-09-22) — maintenance release, no component-specific changes
- **1.326.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **1.303.0** (2026-07-23) — maintenance release, no component-specific changes
- **1.292.0** (2026-06-22) — maintenance release, no component-specific changes
- **1.278.0** (2026-05-08) — maintenance release, no component-specific changes
- **1.273.0** (2026-04-30) — maintenance release, no component-specific changes
- **1.272.0** (2026-04-27) — maintenance release, no component-specific changes
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.260.0** (2026-03-17) — maintenance release, no component-specific changes
- **1.254.0** (2026-02-03) — maintenance release, no component-specific changes
- **1.247.2** (2026-01-21) — maintenance release, no component-specific changes
- **1.232.0** (2025-11-28) — maintenance release, no component-specific changes
- **1.213.0** (2025-08-19) — maintenance release, no component-specific changes
- **1.206.0** (2025-07-16) — maintenance release, no component-specific changes
- **1.202.0** (2025-06-27) — maintenance release, no component-specific changes
- **1.201.0** (2025-06-23) — fix: improve accessibility ([#14990](invalid-url))
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.120.1** (2024-08-08) — maintenance release, no component-specific changes
- **1.120.0** (2024-08-02) — maintenance release, no component-specific changes
- **1.115.0** (2024-07-17) — maintenance release, no component-specific changes
- **1.103.3** (2024-04-30) — maintenance release, no component-specific changes
- **1.103.1** (2024-04-24) — maintenance release, no component-specific changes
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.100.0** (2024-04-04) — maintenance release, no component-specific changes
- **1.99.1** (2024-04-02) — feat: add paddings and margins for mobile ([#13558](invalid-url))
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes