Skip to main content

Starwind UI v3.0 is now available! Migration guide

Radio Group

Choose an option

Installation

Usage

---
import { RadioGroup, RadioGroupItem } from "@/components/starwind/radio-group";
import { Label } from "@/components/starwind/label";
---
<RadioGroup name="demo-radio" defaultValue="option-1" legend="Choose an option">
<div class="flex gap-2 items-center">
<RadioGroupItem id="option-1" aria-label="Option 1" value="option-1" />
<Label for="option-1">Option 1</Label>
</div>
<div class="flex gap-2 items-center">
<RadioGroupItem id="option-2" aria-label="Option 2" value="option-2" />
<Label for="option-2">Option 2</Label>
</div>
<div class="flex gap-2 items-center">
<RadioGroupItem id="option-3" aria-label="Option 3" value="option-3" />
<Label for="option-3">Option 3</Label>
</div>
</RadioGroup>

Composition

Place each radio item inside the group:

RadioGroup
├── RadioGroupItem
└── RadioGroupItem

Variants

Default
Primary
Secondary
Info
Success
Warning
Error

Sizes

Set the radio indicator scale once on RadioGroup. RadioGroupItem no longer accepts size. Labels are separate components outside the Radio Group’s styled scope, so size each Label independently when you want its typography to match.

Small
Medium
Large

Orientation

Vertical (Default)

Vertical options

Horizontal

Horizontal options

Accessibility adjustment

Give each Runtime radio an explicit accessible name. The styled radio uses a focusable role="radio" element while its hidden input handles native form participation.

Event Handling

The RadioGroup component emits a starwind:value-change event when a radio option is selected. This can be listened to in order to update your UI based on the event.detail.value property.

Radio Group Event Test

Choose an option
Selected value: none

Size Migration

BeforeAfter
<RadioGroup><RadioGroupItem size="sm" /></RadioGroup><RadioGroup size="sm"><RadioGroupItem /></RadioGroup>

External Label components remain independently sizeable.

API Reference

Styled Component API

These props are added or materially changed by the installed styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Expand a prop to see named type definitions and framework-specific imports. Follow the Primitive and Runtime links for lower-level behavior props.

Radio Group

Inherits div attributes. Omits `defaultValue` and `onChange`.

Contains the following additional props:

Prop Type Default Toggle details
defaultValue string
Description
Sets the initial value when the component is uncontrolled.
Classification
Primitive override
Primitive prop
radio-group.Root.defaultValue
legend string
Description
Provides accessible text for the grouped choices.
Classification
Wrapper prop
orientation "vertical" | "horizontal" "vertical"
Description
Selects the horizontal or vertical layout direction.
Classification
Styled variant
Primitive prop
radio-group.Root.orientation
size "sm" | "md" | "lg" "md"
Description
Selects the component's visual size.
Classification
Wrapper prop
value string
Description
Controls or identifies the component value.
Classification
Primitive override
Type imports
React import type { RadioGroupValue } from "@starwind-ui/react";
Primitive prop
radio-group.Root.value

Radio Group Item

Inherits span attributes. Omits `defaultChecked` and `onChange`.

Contains the following additional props:

Prop Type Default Toggle details
defaultChecked boolean
Description
Sets the initial checked state when the choice is uncontrolled.
Classification
Primitive override
Primitive prop
radio.Root.defaultChecked
variant "default" | "primary" | "secondary" | "info" | "success" | "warning" | "error" "default"
Description
Selects the component's visual variant.
Classification
Styled variant

Primitive And Runtime API

Use these references when you need the lower-level behavior APIs behind Radio Group.

Runtime API

Radio primitive
createRadio from @starwind-ui/runtime/radio
Radio Group primitive
createRadioGroup from @starwind-ui/runtime/radio-group

Changelog

View version history v3.0.2 12 releases

v3.0.2

  • Radio Group items now use the neutral default variant when variant is omitted.

v3.0.1

  • Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

v3.0.0

  • Moved radio indicator sizing from RadioGroupItem to RadioGroup, with md as the default.
  • Migration: <RadioGroupItem size="sm" /> becomes <RadioGroup size="sm"><RadioGroupItem /></RadioGroup>. Keep size on external Label components when desired.

v2.0.0

  • Rebuilt Radio Group on Starwind Runtime for radio ownership, form participation, keyboard navigation, and value details.
  • See the Radio Primitive and Radio Group Primitive for the underlying unstyled anatomy and behavior API.

v1.2.6

  • Refactor tailwind variants functions into separate variants.ts file

v1.2.4

  • Add starwind:init event listener to enable initialization of additional Radio Groups loaded after an initial page load, such as when using server islands

v1.2.3

  • add aria-invalid styling

v1.2.2

  • Removed debug logging statements

v1.2.1

  • Add named slot “icon” to RadioGroupItem to enable easy icon swapping

v1.2.0

  • style and focus state updates

v1.1.0

  • Add data-slot attribute to enable global styling updates

v1.0.0

  • Initial release with starwind v1.7.0