Heimerle + Meule Logo
Heimerle + Meule

Radio Group

Radio Groups allow users to select a single option from a list of mutually exclusive choices.

Quick Start

Use a Radio Group when users must select exactly one option from a set.

1import {
2RadioGroup,
3RadioGroupItem 
4} from "@ecos/ui";
5
6<RadioGroup label="Contact preference" defaultValue="email">
7  <RadioGroupItem value="email" label="Email" />
8  <RadioGroupItem value="phone" label="Phone" />
9  <RadioGroupItem value="sms" label="SMS" />
10</RadioGroup>

Controlled Usage

The selected option can be controlled externally using the value and onValueChange props.

1const [value, setValue] = useState("email");
2
3<RadioGroup
4  label="Contact preference"
5  value={value}
6  onValueChange={setValue}
7>
8  <RadioGroupItem value="email" label="Email" />
9  <RadioGroupItem value="phone" label="Phone" />
10  <RadioGroupItem value="sms" label="SMS" />
11</RadioGroup>

Group Labels

Provide a group label to describe the set of available options.

1<RadioGroup label="Preferred contact method">
2  <RadioGroupItem value="email" label="Email" />
3  <RadioGroupItem value="phone" label="Phone" />
4</RadioGroup>

Option Labels

Each radio option should include a label that clearly describes the choice.

1<RadioGroup label="Theme">
2  <RadioGroupItem value="light" label="Light" />
3  <RadioGroupItem value="dark" label="Dark" />
4</RadioGroup>

Help Text

Use helpText to provide additional guidance or context.

Select your preferred contact method.

1<RadioGroup
2  label="Contact preference"
3  helpText="Select your preferred contact method."
4>
5  <RadioGroupItem value="email" label="Email" />
6  <RadioGroupItem value="phone" label="Phone" />
7</RadioGroup>

Radio Group States

Use the state prop to communicate validation and feedback states.

Please select an option.

Selection confirmed.

1<RadioGroup
2  label="Contact preference"
3  state="error"
4  helpText="Please select an option."
5>
6  <RadioGroupItem value="email" label="Email" />
7  <RadioGroupItem value="phone" label="Phone" />
8</RadioGroup>
9
10<RadioGroup
11  label="Contact preference"
12  state="success"
13  helpText="Selection confirmed."
14>
15  <RadioGroupItem value="email" label="Email" />
16  <RadioGroupItem value="phone" label="Phone" />
17</RadioGroup>

Required Fields

Use the required prop to indicate that a selection must be made before submission.

1<RadioGroup
2  label="Subscription plan"
3  required
4>
5  <RadioGroupItem value="basic" label="Basic" />
6  <RadioGroupItem value="premium" label="Premium" />
7</RadioGroup>

Disabled State

Disable the entire group to prevent interaction.

1<RadioGroup
2  label="Account Type"
3  disabled
4>
5  <RadioGroupItem value="personal" label="Personal" />
6  <RadioGroupItem value="business" label="Business" />
7</RadioGroup>

Disabled Option

Individual options can be disabled when they are unavailable.

1<RadioGroup label="Delivery Method">
2  <RadioGroupItem value="standard" label="Standard" />
3  <RadioGroupItem value="express" label="Express" disabled />
4</RadioGroup>

Horizontal Layout

Radio Groups are displayed horizontally by default.

1<RadioGroup label="Size" defaultValue="medium">
2  <RadioGroupItem value="small" label="Small" />
3  <RadioGroupItem value="medium" label="Medium" />
4  <RadioGroupItem value="large" label="Large" />
5</RadioGroup>

Vertical Layout

Use custom classes to change the layout direction.

1<RadioGroup
2  label="Size"
3  className="flex-col gap-3"
4  defaultValue="medium"
5>
6  <RadioGroupItem value="small" label="Small" />
7  <RadioGroupItem value="medium" label="Medium" />
8  <RadioGroupItem value="large" label="Large" />
9</RadioGroup>

Custom IDs

Supply an id when integrating with forms, testing, or analytics.

1<RadioGroup label="Notifications">
2  <RadioGroupItem
3    id="notifications-email"
4    value="email"
5    label="Email"
6  />
7</RadioGroup>

Radio Item Without Label

Radio items can be rendered without labels when used in custom layouts.

1<RadioGroup>
2  <RadioGroupItem value="option-1" />
3</RadioGroup>

API Reference

RadioGroup

Property

Type

Default

Description

labelstring-Label displayed above the radio group.
helpTextstring-Additional descriptive text displayed below the radio group.
state"default" | "error" | "success""default"Controls the validation state styling applied to the group label and help text.
requiredbooleanfalseDisplays a required indicator alongside the group label.
valuestring-Controls the selected value.
defaultValuestring-Sets the initial selected value when uncontrolled.
onValueChange(value) => void-Called when the selected value changes.
disabledbooleanfalseDisables the entire radio group.
classNamestring-Additional classes applied to the radio group container.

RadioGroupItem

Property

Type

Default

Description

labelstring-Label displayed alongside the radio item.
valuestring-The value associated with the radio item.
disabledbooleanfalsePrevents interaction with the individual radio item.
classNamestring-Additional classes applied to the radio item.

Visual Reference

Configuration

Preview

Default
With Help Text

Select your preferred contact method

Error State

Please select an option.

Success State

Selection confirmed.

Selected
Required
Disabled Group
Disabled Option
Vertical Layout
Without Labels