Radio

A radio button is a form control that allows users to select one option from a group of choices. Selecting a new option automatically deselects the previously selected one.

Use radio buttons when users need to make a single, mutually exclusive choice within a list of two or more options.

Common alternative names:
Option Button, Choice Button, Single-Select

---

Variants

Active

A radio button in its selected state.

Preview

Code

RadioButton<bool>(
  value: true,
)

---

Inactive

A radio button in its unselected state.

Preview

Code

RadioButton<bool>(
  value: false,
)

---

Error

A radio button displaying an error state with error coloring.

Preview

Code

RadioButton<bool>(
  value: true,
  isError: true,
)

---

With Description

A radio button with both label and description text.

Preview

Code

RadioButton<bool>(
  value: true,
  label: 'Title',
  description: 'Caption',
)

---

Interactive Group

A practical example showing multiple radio buttons working together as a group.

Preview

Code

enum RadioOption { option1, option2 }
RadioOption? selectedOption;

Row(
  spacing: 24,
  mainAxisSize: MainAxisSize.min,
  children: [
    RadioButton<RadioOption>(
      value: RadioOption.option1,
      label: 'Option 1',
      groupValue: selectedOption,
      onChanged: (val) => setState(() => selectedOption = val),
    ),
    RadioButton<RadioOption>(
      value: RadioOption.option2,
      label: 'Option 2',
      groupValue: selectedOption,
      onChanged: (val) => setState(() => selectedOption = val),
    ),
  ],
)

---

Properties

Property	Type	Description
value	T	The value represented by this radio button.
groupValue	T?	The currently selected value for the radio button group.
onChanged	ValueChanged<T?>?	Called when the radio button is selected.
label	String?	Optional text label to display next to the radio button.
labelStyle	TextStyle?	Custom text style for the label.
description	String?	Optional description text displayed below the label.
descriptionStyle	TextStyle?	Custom text style for the description text.
size	double	The size of the radio button circle in logical pixels. Default is 20.0.
spacing	double	The spacing between the radio button and text content. Default is 12.0.
readOnly	bool	Whether the radio button is read-only. Default is false.
isError	bool	Whether the radio button should display in an error state. Default is false.