Radio

Migration guide for Radio from HeroUI v2 to v3

Refer to the v3 Radio documentation for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.

Structure Changes

In v2, Radio used a simple structure with props:

1import { RadioGroup, Radio } from "@lenso/ui";2
3export default function App() {4  return (5    <RadioGroup label="Select city">6      <Radio value="london">London</Radio>7      <Radio value="tokyo" description="Capital of Japan">Tokyo</Radio>8    </RadioGroup>9  );10}

In v3, Radio requires compound components:

1import { RadioGroup, Radio, Label, Description } from "@lenso/ui";2
3export default function App() {4  return (5    <RadioGroup>6      <Label>Select city</Label>7      <Radio value="london">8        <Radio.Content>9          <Radio.Control>10            <Radio.Indicator />11          </Radio.Control>12          London13        </Radio.Content>14      </Radio>15      <Radio value="tokyo">16        <Radio.Content>17          <Radio.Control>18            <Radio.Indicator />19          </Radio.Control>20          Tokyo21        </Radio.Content>22        <Description>Capital of Japan</Description>23      </Radio>24    </RadioGroup>25  );26}

Key Changes

1. Component Structure

v2: Simple Radio with children as label
v3: Compound components: Radio.Content, Radio.Control, Radio.Indicator

2. Prop Changes

v2 Prop	v3 Location	Notes
`onValueChange`	`onChange`	Renamed event handler
`label` (on RadioGroup)	—	Use `Label` component
`description` (on Radio)	—	Use `Description` component as a sibling of `Radio.Content`
`size`	—	Removed (use Tailwind CSS)
`color`	—	Removed (use Tailwind CSS)
`classNames`	—	Use `className` props on individual components
`disableAnimation`	—	Removed (animations handled differently)
—	`variant`	New prop on `RadioGroup`: `"primary"` (default) or `"secondary"` for lower emphasis styling
—	`isReadOnly`	New prop on `RadioGroup`: prevents value changes while keeping the group focusable

Migration Examples

Form Validation

1{/* With description */}2<RadioGroup label="Select city">3  <Radio value="london" description="Capital of England">4    London5  </Radio>6</RadioGroup>7
8{/* With validation */}9<RadioGroup10  isInvalid11  errorMessage="Please select an option"12  label="Select city"13>14  <Radio value="london">London</Radio>15</RadioGroup>

Controlled

1import { useState } from "react";2
3const [selected, setSelected] = useState("london");4
5<RadioGroup6  value={selected}7  onValueChange={setSelected}8>9  <Radio value="london">London</Radio>10  <Radio value="tokyo">Tokyo</Radio>11</RadioGroup>

Horizontal Orientation

1<RadioGroup orientation="horizontal" label="Select city">2  <Radio value="london">London</Radio>3  <Radio value="tokyo">Tokyo</Radio>4</RadioGroup>

Variants

v3 introduces a variant prop on RadioGroup with "primary" (default) and "secondary" options:

1{/* Primary variant (default) */}2<RadioGroup variant="primary">3  <Label>Select city</Label>4  <Radio value="london">5    <Radio.Content>6      <Radio.Control>7        <Radio.Indicator />8      </Radio.Control>9      London10    </Radio.Content>11  </Radio>12</RadioGroup>13
14{/* Secondary variant - lower emphasis, suitable for Surface components */}15<RadioGroup variant="secondary">16  <Label>Select city</Label>17  <Radio value="london">18    <Radio.Content>19      <Radio.Control>20        <Radio.Indicator />21      </Radio.Control>22      London23    </Radio.Content>24  </Radio>25</RadioGroup>

Read Only

v3 supports isReadOnly on RadioGroup, which prevents value changes while keeping the group focusable:

1<RadioGroup isReadOnly defaultValue="london">2  <Label>Select city</Label>3  <Radio value="london">4    <Radio.Content>5      <Radio.Control>6        <Radio.Indicator />7      </Radio.Control>8      London9    </Radio.Content>10  </Radio>11  <Radio value="tokyo">12    <Radio.Content>13      <Radio.Control>14        <Radio.Indicator />15      </Radio.Control>16      Tokyo17    </Radio.Content>18  </Radio>19</RadioGroup>

Component Anatomy

The v3 Radio follows this structure:

1RadioGroup (Root)2  ├── Label (optional)3  ├── Radio4  │   ├── Radio.Content (the clickable label)5  │   │   ├── Radio.Control6  │   │   │   └── Radio.Indicator7  │   │   └── Label8  │   └── Description (optional, sibling)9  └── FieldError (optional)

Summary

Component Structure: Must use compound components (Radio.Content, Radio.Control, Radio.Indicator)
Label Handling: label prop removed - use Label component
Description Handling: description prop removed - use Description component as a sibling of Radio.Content
Event Handler: onValueChange → onChange
Styling Props Removed: size, color - use Tailwind CSS
ClassNames Removed: Use className props on individual components
Error Message: Use FieldError component instead of errorMessage prop
New variant Prop: RadioGroup supports "primary" (default) and "secondary" for lower emphasis styling
New isReadOnly Prop: RadioGroup supports isReadOnly to prevent value changes while keeping the group focusable