On this page

Radio Primitive

Radio is a Starwind Runtime primitive in the single-boolean-control 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 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

React

Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.

checked
defaultChecked
onCheckedChange

Astro

Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.

checked
defaultChecked
starwind:checked-change
setChecked

Runtime / HTML

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

data-default-checked
starwind:checked-change
setChecked

defaultChecked boolean false

Description

Sets whether Radio starts checked for uncontrolled usage.

Kind

control

Targets

Full type

boolean

React

Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.

checked
defaultChecked
onCheckedChange

Astro

Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.

checked
defaultChecked
starwind:checked-change
setChecked

Runtime / HTML

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

data-default-checked
starwind:checked-change
setChecked

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

React

Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.

checked
defaultChecked
onCheckedChange

Astro

Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.

checked
defaultChecked
starwind:checked-change
setChecked

Runtime / HTML

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

data-default-checked
starwind:checked-change
setChecked

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

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

checked boolean checked / defaultChecked

Description

Tracks whether Radio is checked.

Initial attribute

data-default-checked

Runtime getter

getChecked

Runtime setter

setChecked

React

Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.

checked
defaultChecked
onCheckedChange

Astro

Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.

checked
defaultChecked
starwind:checked-change
setChecked

Runtime / HTML

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

data-default-checked
starwind:checked-change
setChecked

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

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 state after accepted Runtime transitions and external state changes.

v0.1.0

Introduced radio item checked state, disabled behavior, and native form participation.

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

Changelog

v1.0.0

v0.1.2

v0.1.1

v0.1.0