On this page

Radio Group Primitive

Radio Group is a Starwind Runtime primitive in the controlled-value-group contract family. Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.

Anatomy

Use the Astro primitive adapter to render RadioGroup anatomy with the Runtime wiring included.

---
import { RadioGroup } from "@starwind-ui/astro/radio-group";
---

<RadioGroup.Root />

Use the React primitive adapter when RadioGroup state participates in React rendering.

import { RadioGroup } from "@starwind-ui/react/radio-group";

export function Example() {
  return (
    <RadioGroup.Root />
  );
}

Render the RadioGroup data-sw-* contract yourself, then initialize createRadioGroup.

<div data-sw-radio-group role="radiogroup"></div>

<script type="module">
  import { createRadioGroup } from "@starwind-ui/runtime/radio-group";

  const root = document.querySelector("[data-sw-radio-group]");
  if (root) {
    createRadioGroup(root);
  }
</script>

API Reference

Root

The main element that owns the Radio Group Runtime instance.

Default element: div
Discovery hook: data-sw-radio-group
Role: radiogroup

Props

Prop Type Default

value RadioGroupValue -

Description

Controls the current Radio Group value.

Kind

control

Targets

Full type

RadioGroupValue

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

defaultValue RadioGroupValue -

Description

Sets the initial Radio Group value for uncontrolled usage.

Kind

control

Targets

Full type

RadioGroupValue

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

disabled boolean false

Description: Disables the Root part.
Kind: option
Targets: -
Full type: boolean

form string -

Description: Associates the control with a form element.
Kind: option
Targets: -
Full type: string

name string -

Description: Sets the submitted form field name.
Kind: option
Targets: -
Full type: string

orientation "horizontal" | "vertical" "vertical"

Description: Sets the Radio Group orientation.
Kind: option
Targets: -
Full type: "horizontal" | "vertical"

readOnly boolean false

Description: Marks the control as read-only.
Kind: option
Targets: -
Full type: boolean

required boolean false

Description: Marks the form control as required.
Kind: option
Targets: -
Full type: boolean

onValueChange (value: string, details: RadioGroupValueChangeDetails) => void -

Description

Runs when the Radio Group value changes.

Kind

callback

Targets

Full type

(value: string, details: RadioGroupValueChangeDetails) => void

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

Events

Event Callback Value

valueChange onValueChange value: string

Description

Fires when the value changes for Radio Group.

DOM event

starwind:value-change

Details type

RadioGroupValueChangeDetails

Timing

before-state-commit

Cancelable

Yes

Cancellation sequence

Check internal eligibility and intent.
Create one details object for the proposal.
Call the Runtime callback with the details object when the controller exposes one.
Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.
Read details.isCanceled, including cancellation caused by preventDefault().
Apply the accepted state.
Notify Runtime subscribers and other accepted-only observers.

State

State Type Props

value RadioGroupValue value / defaultValue

Description

Tracks the current Radio Group value.

Initial attribute

data-default-value

Runtime getter

getValue

Runtime setter

setValue

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-radio-group - Marks the Root part so Starwind Runtime can find it.

State

Attribute Value Description

data-value - Reflects the value state on the Root part.

Metadata

Attribute Value Description

data-default-value - Reflects the default value prop on the Root part.

data-disabled - Reflects the disabled prop on the Root part.

data-form - Reflects the form prop on the Root part.

data-name - Reflects the name prop on the Root part.

data-orientation - Reflects the orientation prop on the Root part.

data-readonly - Reflects the readonly prop on the Root part.

data-required - Reflects the required prop on the Root part.

Runtime API

Factory: createRadioGroup
Import: @starwind-ui/runtime/radio-group
Root hook: root data-sw-radio-group
Option props: defaultValue, disabled, form, name, orientation, readOnly, required, value

Runtime Setters

Method Target Description

setValue state: value Updates the current Radio Group value from Runtime code.

setDisabled prop: disabled Updates whether Radio Group is disabled from Runtime code.

setFormOptions props: form, name, required Updates Radio Group form-related options from Runtime code.

setName prop: name Updates the Radio Group form field name from Runtime code.

setOrientation prop: orientation Updates the Radio Group orientation from Runtime code.

setReadOnly prop: readOnly Updates whether Radio Group is read-only from Runtime code.

setRequired prop: required Updates whether Radio Group is required from Runtime code.

Form Participation

Fact	Value
Form props	form, name, required, value
Hidden input	-
Field integration	Yes

Component Relationship

Radio Group Composite

Changelog

View version history v1.0.0 4 releases

v1.0.0

Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.

v0.1.2

Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.

v0.1.1

Synchronized vendored React Radio Group state after accepted Runtime transitions and external state changes.

v0.1.0

Introduced grouped radio ownership, roving keyboard focus, value changes, and form participation.

Layer Metadata

Radio Group Primitive uses createRadioGroup. Styled components: Radio Group.

primitive Radio Group Primitive Radio Group Primitive uses createRadioGroup. Styled components: Radio Group. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters radio-group Radio Group Controlled Value Group Grouped controls coordinated by a shared selected value. /docs/primitives/radio-group/ createRadioGroup @starwind-ui/runtime/radio-group /docs/runtime/#create-radio-group root defaultValue disabled form name orientation readOnly required value raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the RadioGroup data-sw-* contract yourself, then initialize createRadioGroup. html Use the Astro primitive adapter to render RadioGroup anatomy with the Runtime wiring included. Use the React primitive adapter when RadioGroup state participates in React rendering. tsx div data-sw-radio-group radiogroup RadioGroupValue Controls the current Radio Group value. Sets the initial Radio Group value for uncontrolled usage. boolean Disables the Root part. string Associates the control with a form element. Sets the submitted form field name. "horizontal" | "vertical" Sets the Radio Group orientation. Marks the control as read-only. Marks the form control as required. onValueChange (value: string, details: RadioGroupValueChangeDetails) => void RadioGroupValueChangeDetails Runs when the Radio Group value changes. runtime Marks the Root part so Starwind Runtime can find it. data-default-value prop Reflects the default value prop on the Root part. data-disabled Reflects the disabled prop on the Root part. data-form Reflects the form prop on the Root part. data-name Reflects the name prop on the Root part. data-orientation Reflects the orientation prop on the Root part. data-readonly Reflects the readonly prop on the Root part. data-required Reflects the required prop on the Root part. data-value state Reflects the value state on the Root part. getValue setValue valueChange starwind:value-change setDisabled setFormOptions form, name, required setName setOrientation setReadOnly setRequired Root aria-disabled aria-orientation aria-readonly aria-required @starwind-ui/astro @starwind-ui/astro/radio-group Render uncontrolled initial group value only; child Radio coordination and roving focus are runtime-owned. @starwind-ui/react @starwind-ui/react/radio-group Bridge controlled value updates through setValue and provide framework context so child Radio components can derive effective form, disabled, readOnly, required, and value props. /docs/components/radio-group/ Composite composite The styled radio group combines group-level behavior with individual radio items. Styled component Radio Group

Radio Group Primitive

Anatomy

API Reference

Root

Props

Events

State

Data Attributes

Runtime hooks

State

Metadata

Runtime API

Runtime Setters

Form Participation

Related Styled Components

Changelog

v1.0.0

v0.1.2

v0.1.1

v0.1.0