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.1.0 15 releases

v3.1.0

  • In Svelte, a defined value, or a defined checked on an item, that you pass when RadioGroup mounts now stays under your control, as in React and Vue. To change it, use bind: or update your state in the change callback. A form reset keeps it. If you pass undefined at mount, RadioGroup keeps its own state.

v3.0.4

  • Each radio now gets its name from a <label for> that points at its id. Before, screen readers read the radios with no name.
  • In Astro, a required Radio Group in a plain HTML form now shows the browser message and gets focus. Before, the form did not submit, and no message showed.
  • When a required Radio Group is the first field with an error in a Starwind Form, submit and validate({ focus: true }) now put focus on the checked radio, or on the first radio, and the page scrolls to it.
  • When the browser flags a required Radio Group as invalid, focus now goes to the radio that the user sees.

v3.0.3

  • Reduced the JavaScript loaded by Radio Group when it is used without Field.

v3.0.2

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

v3.0.1

  • The default export in index.ts now has a name, RadioGroupParts, so framework tools show a clear name.

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

  • Radio Group now gets its behavior from Starwind Runtime. Runtime connects each radio to its group and handles the form value, keyboard navigation, and the details in value-change events.
  • See the Radio Primitive and Radio Group Primitive for the unstyled parts and the behavior API.

v1.2.6

  • The Tailwind variants now live in their own variants.ts file in the component folder.

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