Components/Form
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/radio
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.
<RadioGroup/> in a custom design.<RadioGroup/> instead.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.
Control the state of a component with:
checked - use it to mark an active selectiondisabled - use it to mark an item that cannot be selectedAdd 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/>.
Control radio alignment to a label with alignItems prop. It supports 2 values:
center (default) - use it in all common casestop - use it to align a radio to the top to handle text overflowAny component or a set of components can be passed as a radio option label.
Use <InfoIcon/> to provide additional information about a selection.
A radio can be used to build custom selection lists using <Card/> as a base for each option
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.
| 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. |
Import the driver matching your test environment:
| 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. |
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)Last updated: 22 October 2026