> 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: Radio Component

## Article: Radio Component

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

## Article Content:

# Radio

_Components/Form_

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

## Overview

```jsx
<Box align="center">
  <Box gap="6px">
    <Radio label="Add to total at the checkout" checked />
    <InfoIcon content="Tax is charged to the customer, it won't be included in the price of your plans. They'll see it added to the price at the checkout." />
  </Box>
</Box>;
```

A radio represents an item in a single selection list. It is used as an internal part of `<RadioGroup/>`, but can be used as a standalone item in a custom form or layout.

### Do

- Use it to recreate `<RadioGroup/>` in a custom design.

### Don't

- Don't use it to display a regular list of single selection options. Use `<RadioGroup/>` instead.

### Feature examples

#### Structure

The component consists of a radio and label that represents the selection value. By default, `label` is a text string but can be overridden to any other component or a set of components.

```jsx
<Radio label="Label" />;
```

#### States

Control the state of a component with:

- `checked` - use it to mark an active selection
- `disabled` - use it to mark an item that cannot be selected

```jsx
<StorybookComponents.Stack flexDirection="column">
  <Radio label="Default" />
  <Radio label="Checked" checked />
  <Radio label="Disabled" disabled />
</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 button 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.">
  <Radio label="Radio button" />
</FormField>;
```

#### Alignment

Control radio alignment to a label with `alignItems` prop. It supports 2 values:

- `center` (default) - use it in all common cases
- `top` - use it to align a radio to the top to handle text overflow

```jsx
<StorybookComponents.Stack width="300px">
  <Radio
    alignItems="top"
    label="Radio button label that wraps to multiple lines"
  />
</StorybookComponents.Stack>;
```

### Common use case examples

#### Custom label

Any component or a set of components can be passed as a radio option label.

```jsx
() => {
  const [checked, setChecked] = React.useState(false);

  return (
    <Radio
      checked={checked}
      onChange={() => setChecked(true)}
      label={
        <Cell>
          <Heading size="small">Free plan</Heading>
          <Text size="small" secondary>
            Offer your plan free of charge.
          </Text>
        </Cell>
      }
    />
  );
};
```

#### Additional info

Use `<InfoIcon/>` to provide additional information about a selection.

```jsx
() => {
  const [checked, setChecked] = React.useState(false);

  return (
    <Box inline gap="6px">
      <Radio
        label="Add total at checkout"
        checked={checked}
        onChange={() => setChecked(true)}
      />
      <InfoIcon content="Tax is charged to a customer, it won't be included in the price of your plans. They'll see it added to the price at a checkout." />
    </Box>
  );
};
```

#### Custom layout

A radio can be used to build custom selection lists using `<Card/>` as a base for each option

```jsx
() => {
  const [checkedId, setCheckedId] = React.useState(0);

  return (
    <Layout cols={1} gap="12px">
      <Card>
        <Box padding="18px 24px">
          <Radio
            checked={checkedId === 1}
            onChange={() => setCheckedId(1)}
            label={
              <Box direction="vertical">
                <Heading size="small">Free plan</Heading>
                <Text size="small" secondary>
                  Offer your plan free of charge
                </Text>
              </Box>
            }
          />
        </Box>
      </Card>
      <Card>
        <Box padding="18px 24px">
          <Radio
            checked={checkedId === 2}
            onChange={() => setCheckedId(2)}
            label={
              <Box direction="vertical">
                <Heading size="small">One time payment</Heading>
                <Text size="small" secondary>
                  Charge a single upfront fee
                </Text>
              </Box>
            }
          />
        </Box>
      </Card>
      <Card>
        <Box padding="18px 24px">
          <Radio
            checked={checkedId === 3}
            onChange={() => setCheckedId(3)}
            label={
              <Box direction="vertical">
                <Heading size="small">Recurring payment</Heading>
                <Text size="small" secondary>
                  Charge a weekly, monthly or yearly fee
                </Text>
              </Box>
            }
          />
        </Box>
      </Card>
    </Layout>
  );
};
```

### Accessibility examples

#### Labelling a radio without visible text

A radio needs an accessible name. When `label` carries the visible text that name comes for free, but a radio labelled only by a graphic or by text elsewhere needs it supplied:

- `ariaLabel` gives the radio a name directly, for a control whose meaning is carried by an image or icon.
- `ariaLabelledby` points at the id of the element that already labels it, so the name stays in one place.

Prefer `ariaLabelledby` when the labelling text is on screen, screen reader users then hear exactly what everyone else reads.

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

  return (
    <Box direction="vertical" gap="12px">
      <Text id="billing-period-label" weight="bold" size="small">
        Billing period
      </Text>
      <Radio
        label="Monthly"
        ariaLabelledby="billing-period-label"
        checked={value === 'monthly'}
        onChange={() => setValue('monthly')}
      />
      <Radio
        ariaLabel="Yearly billing, two months free"
        checked={value === 'yearly'}
        onChange={() => setValue('yearly')}
        label={<Badge skin="success">Yearly, 2 months free</Badge>}
      />
    </Box>
  );
};
```

## Code

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

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `alignItems` | `"center" \| "top"` | — | Control radio alignment with a label. |
| `ariaLabel` | `string` | — | Sets an accessible name for the radio when no visible label is rendered, applied as `aria-label`. |
| `ariaLabelledby` | `string` | — | Sets the id of the element that labels the radio, applied as `aria-labelledby`. |
| `checked` | `boolean` | — | Specifies whether a radio is selected. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in tests. |
| `disabled` | `boolean` | — | Specifies whether radio should be disabled. |
| `id` | `string` | — | Assigns an unique identifier for the radio. |
| `label` | `ReactNode` | — | Sets the label on the right side of a radio. The default accepted value is a text string, but it can be overridden to any other component. |
| `name` | `string` | — | Sets a unique name for the radio. |
| `onBlur` | `(event: FocusEvent, triggers: Triggers) => void` | — |  |
| `onChange` | `(event: OnChangeEvent) => void` | — | Defines a callback function which is called when radio is selected. |
| `onFocus` | `(event: FocusEvent, triggers: Triggers) => void` | — |  |
| `onMouseEnter` | `(event: OnChangeEvent) => void` | — | Defines a callback function which is called when cursor enters radio. |
| `onMouseLeave` | `(event: OnChangeEvent) => void` | — | Defines a callback function which is called when cursor leaves radio. |
| `ref` | `string & RefObject<HTMLElement> \| ((instance: HTMLInputElement \| null) => void) & RefObject<HTMLElement> \| RefObject<HTMLInputElement> & RefObject<HTMLElement>` | — | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
| `size` | `"small" \| "medium"` | `'medium'` | Controls the size of the label text. |
| `style` | `CSSProperties` | — | Applies inline styles to the component's root element. |
| `value` | `string \| number` | — | Sets the value that the radio represents. |

## Testkit

Import the driver matching your test environment:

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

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

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

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

### Driver methods

| Method | Description |
| --- | --- |
| `keyDown` | Triggers a keyDown event on the radio input. |
| `getValue` | Gets value of radio input. |
| `getName` | Gets name of radio input. |
| `getId` | Gets id of radio input. |
| `getLabel` | Gets label text of radio. |
| `iconExists` | Checks if icon of radio exists. |
| `labelExists` | Checks if label of radio exists. |
| `isChecked` | Checks if radio is checked. |
| `isDisabled` | Checks if radio is disabled. |
| `mouseEnter` | Triggers a mouseEnter event. |
| `mouseLeave` | Triggers a mouseLeave event. |
| `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.331.0** (2026-10-01) — 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.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.324.0** (2026-09-14) — maintenance release, no component-specific changes
- **1.323.0** (2026-09-10) — maintenance release, no component-specific changes
- **1.321.0** (2026-09-08) — feat: added `ariaLabel` and `ariaLabelledby` props to give a radio an accessible name when it has no visible label. The root element no longer carries `aria-checked`; the native input conveys the checked state. ([#17028](invalid-url))
- **1.318.0** (2026-08-28) — feat: the dot animates in and out on selection change in Harmony (odeditor). ([#16927](invalid-url))
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **1.305.1** (2026-07-30) — maintenance release, no component-specific changes
- **1.305.0** (2026-07-28) — maintenance release, no component-specific changes
- **1.303.0** (2026-07-23) — feat: migrate off stylable and add dot animation ([#16590](invalid-url))
- **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.247.2** (2026-01-21) — 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.204.0** (2025-07-03) — breaking: fix label color to match Checkbox (primary text) ([#15032](invalid-url))
- **1.202.0** (2025-06-27) — maintenance release, no component-specific changes
- **1.201.0** (2025-06-23) — maintenance release, no component-specific changes
- **1.191.1** (2025-05-27) — maintenance release, no component-specific changes
- **1.183.0** (2025-04-24) — maintenance release, no component-specific changes
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.115.0** (2024-07-17) — maintenance release, no component-specific changes
- **1.106.0** (2024-05-24) — 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.92.1** (2024-02-05) — maintenance release, no component-specific changes