On this page

Radio Primitive

Radio is a Starwind Runtime primitive in the single-boolean-control contract family.

Anatomy

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

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

<Radio.Root value="option-one">
  <Radio.Indicator />
</Radio.Root>

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

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

export function Example() {
  return (
    <Radio.Root value="option-one">
      <Radio.Indicator />
    </Radio.Root>
  );
}

Render the Radio data-sw-* contract yourself, then initialize createRadio.

<span data-sw-radio role="radio" data-value="option-one">
  <span data-sw-radio-indicator></span>
  <input data-sw-radio-input type="radio" aria-hidden="true" tabindex="-1" />
</span>

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

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

API Reference

Root

The main element that owns the Radio Runtime instance.

Default element: span
Discovery hook: data-sw-radio
Role: radio

Props

Prop Type Default

checked boolean -

Description: Controls whether Radio is checked.
Kind: control
Targets: -
Full type: boolean

defaultChecked boolean false

Description: Sets whether Radio starts checked for uncontrolled usage.
Kind: control
Targets: -
Full type: boolean

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

id string -

Description: Sets the id used by the associated native control.
Kind: option
Targets: -
Full type: string

name string -

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

nativeButton boolean false

Description: Renders the control as a native button element.
Kind: rendering
Targets: root
Full type: boolean

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

value string -

Description: Controls the current Radio value.
Kind: option
Targets: -
Full type: string

onCheckedChange (checked: boolean, details: RadioCheckedChangeDetails) => void -

Description: Runs when the Radio checked state changes.
Kind: callback
Targets: -
Full type: (checked: boolean, details: RadioCheckedChangeDetails) => void

Events

Event Callback Value

checkedChange onCheckedChange checked: boolean

Description: Fires when the checked state changes for Radio.
DOM event: starwind:checked-change
Details type: RadioCheckedChangeDetails
Timing: -
Cancelable: No

State

State Type Props

checked boolean checked / defaultChecked

Description: Tracks whether Radio is checked.
Initial attribute: data-default-checked
Runtime getter: getChecked
Runtime setter: setChecked
State control support: React supports controlled and default state with checked and defaultChecked props. Runtime/HTML reads initial state from data-default-checked, emits starwind:checked-change, and updates with setChecked. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state.

Data Attributes

Runtime hooks

Attribute Value Description

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

State

Attribute Value Description

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

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

Metadata

Attribute Value Description

data-default-checked - Reflects the default checked 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-id - Reflects the id prop on the Root part.

data-name - Reflects the name 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 - Reflects the value prop on the Root part.

Indicator

Visual state indicator rendered by Radio.

Default element: span
Discovery hook: data-sw-radio-indicator
Role: -

Props

Prop Type Default

keepMounted boolean false

Description: Keeps the Indicator part in the DOM when hidden.
Kind: rendering
Targets: indicator
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-radio-indicator - Marks the Indicator part so Starwind Runtime can find it.

State

Attribute Value Description

data-unchecked - Reflects the unchecked state on the Indicator part.

Metadata

Attribute Value Description

data-keep-mounted - Reflects the keep mounted prop on the Indicator part.

Input

The native input synchronized by Radio.

Default element: input
Discovery hook: data-sw-radio-input
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-radio-input - Marks the Input part so Starwind Runtime can find it.

Runtime API

Factory: createRadio
Import: @starwind-ui/runtime/radio
Root hook: root data-sw-radio
Option props: checked, defaultChecked, disabled, form, id, name, readOnly, required, value

Runtime Setters

Method Target Description

setChecked state: checked Updates whether Radio is checked from Runtime code.

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

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

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

Form Participation

Fact	Value
Form props	form, id, name, required, value
Hidden input	input (radio)
Field integration	Yes

Component Relationship

Radio Group Composite

Layer Metadata

Radio Primitive uses createRadio. Styled components: Radio Group.

primitive Radio Primitive Radio Primitive uses createRadio. Styled components: Radio Group. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters radio Radio Single Boolean Control Controls with a single checked, pressed, or enabled state. /docs/primitives/radio/ createRadio @starwind-ui/runtime/radio /docs/runtime/#create-radio root checked defaultChecked disabled form id name readOnly required value raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Radio data-sw-* contract yourself, then initialize createRadio. html Use the Astro primitive adapter to render Radio anatomy with the Runtime wiring included. Use the React primitive adapter when Radio state participates in React rendering. tsx span data-sw-radio boolean Controls whether Radio is checked. Sets whether Radio starts checked for uncontrolled usage. Disables the Root part. string Associates the control with a form element. Sets the id used by the associated native control. Sets the submitted form field name. nativeButton Renders the control as a native button element. Marks the control as read-only. Marks the form control as required. Controls the current Radio value. onCheckedChange (checked: boolean, details: RadioCheckedChangeDetails) => void RadioCheckedChangeDetails Runs when the Radio checked state changes. runtime Marks the Root part so Starwind Runtime can find it. data-checked state Reflects the checked state on the Root part. data-default-checked prop Reflects the default checked 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-id Reflects the id prop on the Root part. data-name Reflects the name 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-unchecked Reflects the unchecked state on the Root part. data-value Reflects the value prop on the Root part. getChecked setChecked checkedChange starwind:checked-change setDisabled setReadOnly setFormOptions form, name, required, value indicator data-sw-radio-indicator keepMounted Keeps the Indicator part in the DOM when hidden. Marks the Indicator part so Starwind Runtime can find it. data-keep-mounted Reflects the keep mounted prop on the Indicator part. Reflects the unchecked state on the Indicator part. input data-sw-radio-input Marks the Input part so Starwind Runtime can find it. Root aria-checked Indicator Input type aria-hidden tabIndex @starwind-ui/astro @starwind-ui/astro/radio Render uncontrolled initial state only; updates are runtime-owned after hydration. @starwind-ui/react @starwind-ui/react/radio Bridge controlled checked changes through setChecked and derive effective form/name/required/readOnly state from RadioGroup context. radio-group Radio Group /docs/components/radio-group/ Composite composite The styled radio group combines group-level behavior with individual radio items. Styled component Radio Group

Radio Primitive

Anatomy

API Reference

Root

Props

Events

State

Data Attributes

Runtime hooks

State

Metadata

Indicator

Props

Data Attributes

Runtime hooks

State

Metadata

Input

Data Attributes

Runtime hooks

Runtime API

Runtime Setters

Form Participation

Related Styled Components