# 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
### Astro
Use the Astro primitive adapter to render RadioGroup anatomy with the Runtime wiring included.
```astro
---
import { RadioGroup } from "@starwind-ui/astro/radio-group";
---

<RadioGroup.Root />
```

### React
Use the React primitive adapter when RadioGroup state participates in React rendering.
```tsx
import { RadioGroup } from "@starwind-ui/react/radio-group";

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

### HTML
Render the RadioGroup data-sw-* contract yourself, then initialize createRadioGroup.
```html
<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>
```

### Vue
Use the Vue 3.5 beta adapter to render RadioGroup anatomy.
```vue
<script setup lang="ts">
import RadioGroup from "@starwind-ui/vue/radio-group";
</script>

<template>
  <RadioGroup.Root />
</template>
```
## API Reference
### Root
The main element that owns the Radio Group Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-radio-group` |
| Role | `radiogroup` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `RadioGroupValue` | - | control | Controls the current Radio Group value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| defaultValue | `RadioGroupValue` | - | control | Sets the initial Radio Group value for uncontrolled usage. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| form | `string` | - | option | Associates the control with a form element. | - |
| name | `string` | - | option | Sets the submitted form field name. | - |
| orientation | `"horizontal" \| "vertical"` | "vertical" | option | Sets the Radio Group orientation. | - |
| readOnly | `boolean` | false | option | Marks the control as read-only. | - |
| required | `boolean` | false | option | Marks the form control as required. | - |
| onValueChange | `(value: string, details: RadioGroupValueChangeDetails) => void` | - | callback | Runs when the Radio Group value changes. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-radio-group` | 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` | prop | - | Reflects the disabled prop on the Root part. |
| `data-form` | prop | - | Reflects the form prop on the Root part. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-orientation` | prop | - | Reflects the orientation prop on the Root part. |
| `data-readonly` | prop | - | Reflects the readonly prop on the Root part. |
| `data-required` | prop | - | Reflects the required prop on the Root part. |
| `data-value` | state | - | Reflects the value state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `RadioGroupValue` | value | defaultValue | `data-default-value` | `getValue` | `setValue` | Tracks the current Radio Group value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `string` | RadioGroupValueChangeDetails | before-state-commit | Yes | Fires when the value changes for Radio Group. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setValue` | state: value | emit: false | Yes | Updates the current Radio Group value from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Radio Group is disabled from Runtime code. |
| `setFormOptions` | props: form, name, required | - | No | Updates Radio Group form-related options from Runtime code. |
| `setName` | prop: name | - | No | Updates the Radio Group form field name from Runtime code. |
| `setOrientation` | prop: orientation | - | No | Updates the Radio Group orientation from Runtime code. |
| `setReadOnly` | prop: readOnly | - | No | Updates whether Radio Group is read-only from Runtime code. |
| `setRequired` | prop: required | - | No | Updates whether Radio Group is required from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Context
| Name | Direction | Values |
| --- | --- | --- |
| radio-group | provides | disabled, form, name, readOnly, required, value |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-radio-group`, `role`, `aria-disabled`, `aria-orientation`, `aria-readonly`, `aria-required`, `data-default-value`, `data-disabled`, `data-form`, `data-name`, `data-orientation`, `data-readonly`, `data-required`, `data-value` | The radio group needs initial selection, form coordination, and orientation for child radio semantics before hydration. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, name, required, value |
| Hidden input | - |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createRadioGroup`](/docs/runtime/#create-radio-group) |
| Import | `@starwind-ui/runtime/radio-group` |
| Root part | root |
| Option props | defaultValue, disabled, form, name, orientation, readOnly, required, value |
| Option lifecycles | - |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | form, name, required, value |
| Hidden input | - |
| Field integration | Yes |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Radio Group](/docs/components/radio-group/) | Composite |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/radio-group` | `createRadioGroup` |
| Astro Primitive | `@starwind-ui/astro/radio-group` | `RadioGroup`, `RadioGroupRoot` |
| React Primitive | `@starwind-ui/react/radio-group` | `RadioGroup`, `RadioGroupRoot` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `RadioGroup` |
| runtime-factory | `createRadioGroup` |
| part | `RadioGroup.Root` |
## Changelog
### 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.