RadioGroup

Components/Form

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

Overview

Copy

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.

Copy

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

Copy

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.
Copy

Spacing

Control the pixel spacing between options with the spacing prop.

Copy

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.
Copy

Disabled buttons

Radio options can be disabled in 2 ways:

  • Disable all options at once with disabled.
  • Choose which options to disable with disabledRadios.
Copy

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/>.

Copy

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.
Copy

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.

Copy

Common use case examples

Settings panel

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

Copy

Default selection

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

Copy

Additional info

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

Copy

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.

Copy

Custom button

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

Copy

Code

Copy

Props

NameTypeDefaultDescription
childrenReactNode—Lists RadioGroup items. You're recommended to use it with <RadioGroup.Radio/>.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
disabledboolean—Disables the entire group.
disabledRadios(string | number | undefined)[]—Specify the values of the disabled radio buttons.
display"horizontal" | "vertical"'vertical'Control options direction.
fullWidthbooleanfalseMakes component full width and divides all available horizontal space into even parts for each radio button.
namestring—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.
selectionAreaPaddingstring | 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.
spacingstring—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.
valuestring | number''Specifies the selected radio value.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
selectByValueSelects the radio that matches the provided value
selectByIndexSelects the radio in the provided index
getRadioValueAtGet the radio value in the provided index
getRadioAtIndexGet the radio element in the provided index, returns an element merged with the RadioButton driver methods
getSelectedValueGet the value of the selected radio
isRadioDisabledChecks if the radio in the provided index is disabled
getNumberOfRadiosGet the number of rendered radios
getRadioIdAtGet the value of radio button id at the provided index
getRadioNameGet the value of radio button name at the provided index
isRadioCheckedChecks if the radio with the provided index is checked
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns 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)
  • 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)
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?