Radio

Components/Form

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

Overview

Copy

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.

Copy

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
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 button by wrapping it in a <FormField/> and adding statusMessage.

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

Copy

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
Copy

Common use case examples

Custom label

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

Copy

Additional info

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

Copy

Custom layout

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

Copy

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.

Copy

Code

Copy

Props

NameTypeDefaultDescription
alignItems"center" | "top"—Control radio alignment with a label.
ariaLabelstring—Sets an accessible name for the radio when no visible label is rendered, applied as aria-label.
ariaLabelledbystring—Sets the id of the element that labels the radio, applied as aria-labelledby.
checkedboolean—Specifies whether a radio is selected.
dataHookstring—Applies a data-hook HTML attribute that can be used in tests.
disabledboolean—Specifies whether radio should be disabled.
idstring—Assigns an unique identifier for the radio.
labelReactNode—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.
namestring—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.
refstring & 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.
styleCSSProperties—Applies inline styles to the component's root element.
valuestring | number—Sets the value that the radio represents.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
keyDownTriggers a keyDown event on the radio input.
getValueGets value of radio input.
getNameGets name of radio input.
getIdGets id of radio input.
getLabelGets label text of radio.
iconExistsChecks if icon of radio exists.
labelExistsChecks if label of radio exists.
isCheckedChecks if radio is checked.
isDisabledChecks if radio is disabled.
mouseEnterTriggers a mouseEnter event.
mouseLeaveTriggers a mouseLeave event.
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.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)
  • 1.318.0 (2026-08-28) — feat: the dot animates in and out on selection change in Harmony (odeditor). (#16927)
  • 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)
  • 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)
  • 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

Last updated: 22 October 2026

Did this help?