RadioGroup

RadioGroup creates a mutually exclusive selection interface where users can choose only one option from a group of radio buttons. It manages the selection state and ensures that selecting one option automatically deselects all others in the group.Radio options store their values as strings. Numbers and booleans are converted to strings when assigned, while objects, functions and arrays default to an empty string unless resolved via binding expressions.

Key features:

• Exclusive selection: Only one option can be selected at a time within the group
• Form integration: Built-in validation states and seamless form compatibility
• Flexible layout: Contains Option that can be arranged in any layout structure
• State management: Automatically handles selection state and change events
• Accessibility support: Proper keyboard navigation and screen reader compatibility
• Validation indicators: Visual feedback for error, warning, and valid states

RadioGroup is often used in forms. See this guide for details.

Behaviors

This component supports the following behaviors:

Properties

autoFocus

default: false

If this property is set to true, the component gets the focus automatically when displayed.

enabled

default: true

This boolean property value indicates whether the component responds to user events (true) or not (false).

This property indicates whether the input accepts user actions (true) or not (false). The default value is true.

<App>
  <RadioGroup initialValue="first" enabled="false">
    <HStack padding="$space-normal">
      <Option label="First Item" value="first"/>
      <Option label="Second Item" value="second"/>
      <Option label="Third Item" value="third"/>
    </HStack>
  </RadioGroup>
</App>

<App>
  <RadioGroup initialValue="first" enabled="false">
    <HStack padding="$space-normal">
      <Option label="First Item" value="first"/>
      <Option label="Second Item" value="second"/>
      <Option label="Third Item" value="third"/>
    </HStack>
  </RadioGroup>
</App>

initialValue

default: ""

This property sets the component's initial value.

This property defines the initial value of the selected option within the group.

<App>
  <RadioGroup initialValue="first">
    <HStack padding="$space-normal">
      <Option label="First Item" value="first"/>
      <Option label="Second Item" value="second"/>
      <Option label="Third Item" value="third"/>
    </HStack>
  </RadioGroup>
</App>

<App>
  <RadioGroup initialValue="first">
    <HStack padding="$space-normal">
      <Option label="First Item" value="first"/>
      <Option label="Second Item" value="second"/>
      <Option label="Third Item" value="third"/>
    </HStack>
  </RadioGroup>
</App>

readOnly

default: false

Set this property to true to disallow changing the component value.

required

default: false

Set this property to true to indicate it must have a value before submitting the containing form.

validationStatus

default: "none"

This property allows you to set the validation status of the input component.

Available values:

This prop is used to visually indicate status changes reacting to form field validation.

<App>
  <HStack>
    <RadioGroup initialValue="first" validationStatus="error">
      <Option label="First Item" value="first"/>
      <Option label="Second Item" value="second"/>
    </RadioGroup>
    <RadioGroup initialValue="first" validationStatus="warning">
      <Option label="First Item" value="first"/>
      <Option label="Second Item" value="second"/>
    </RadioGroup>
    <RadioGroup initialValue="first" validationStatus="valid">
      <Option label="First Item" value="first"/>
      <Option label="Second Item" value="second"/>
    </RadioGroup>
  </HStack>
</App>

<App>
  <HStack>
    <RadioGroup initialValue="first" validationStatus="error">
      <Option label="First Item" value="first"/>
      <Option label="Second Item" value="second"/>
    </RadioGroup>
    <RadioGroup initialValue="first" validationStatus="warning">
      <Option label="First Item" value="first"/>
      <Option label="Second Item" value="second"/>
    </RadioGroup>
    <RadioGroup initialValue="first" validationStatus="valid">
      <Option label="First Item" value="first"/>
      <Option label="Second Item" value="second"/>
    </RadioGroup>
  </HStack>
</App>

Events

didChange

This event is triggered when value of RadioGroup has changed.

Signature: didChange(newValue: any): void

• newValue: The new value of the component.

This event is triggered after the user has changed the field value. The following example uses this event to display the selected option's value:

<App var.field="">
  <RadioGroup initialValue="{field}" onDidChange="(val) => field = val">
    <Option label="First Item" value="first"/>
    <Option label="Second Item" value="second"/>
  </RadioGroup>
  <Text value="{field}" />
</App>

<App var.field="">
  <RadioGroup initialValue="{field}" onDidChange="(val) => field = val">
    <Option label="First Item" value="first"/>
    <Option label="Second Item" value="second"/>
  </RadioGroup>
  <Text value="{field}" />
</App>

gotFocus

This event is triggered when the RadioGroup has received the focus.

Signature: gotFocus(): void

lostFocus

This event is triggered when the RadioGroup has lost the focus.

Signature: lostFocus(): void

Exposed Methods

setValue

This API sets the value of the RadioGroup. You can use it to programmatically change the value.

Signature: setValue(value: string): void

• value: The new value to set.

You can use this method to set the component's current value programmatically.

<App>
  <RadioGroup id="radio">
    <Option label="First Item" value="first"/>
    <Option label="Second Item" value="second"/>
  </RadioGroup>
  <HStack>
    <Button label="Set First" onClick="radio.setValue('first')" />
    <Button label="Set Second" onClick="radio.setValue('second')" />
  </HStack>
</App>

<App>
  <RadioGroup id="radio">
    <Option label="First Item" value="first"/>
    <Option label="Second Item" value="second"/>
  </RadioGroup>
  <HStack>
    <Button label="Set First" onClick="radio.setValue('first')" />
    <Button label="Set Second" onClick="radio.setValue('second')" />
  </HStack>
</App>

value

This API retrieves the current value of the RadioGroup. You can use it to get the value programmatically.

Signature: get value(): string | undefined

Parts

The component has some parts that can be styled through layout properties and theme variables separately:

• label: The label displayed for the radio group.

Styling

RadioGroup is a component that governs its children and stores the selected value. It does not support styling; however, you can style the options within the group. When you set the theme variables for the group's options, use the RadioGroupOption name.

Theme Variables