Radio Group

Allows single selection from multiple options.

ReactSolidSvelteVue

Anatomy

<RadioGroup.Root>
  <RadioGroup.Label />
  <RadioGroup.Indicator />
  <RadioGroup.Item>
    <RadioGroup.ItemControl />
    <RadioGroup.ItemText />
    <RadioGroup.ItemHiddenInput />
  </RadioGroup.Item>
</RadioGroup.Root>

Examples

Initial Value

To set the radio group's initial value, set the defaultValue prop to the value of the radio item to be selected by default.

Controlled

For a controlled Radio Group, the state is managed using the value prop, and updates when the onValueChange event handler is called:

Root Provider

An alternative way to control the radio group is to use the RootProvider component and the useRadioGroup hook. This way you can access the state and methods from outside the component.

Disabled

To make a radio group disabled, set the disabled prop to true.

Guides

asChild

The RadioGroup.Item component renders as a label element by default. This ensures proper form semantics and accessibility, as radio groups are form controls that require labels to provide meaningful context for users.

When using the asChild prop, you must render a label element as the direct child of RadioGroup.Item to maintain valid HTML structure and accessibility compliance.

// INCORRECT usage ❌
<RadioGroup.Item asChild>
  <div>
    <RadioGroup.ItemHiddenInput />
    <RadioGroup.ItemText>
      <RadioGroup.ItemControl />
    </RadioGroup.ItemText>
  </div>
</RadioGroup.Item>

// CORRECT usage ✅
<RadioGroup.Item asChild>
  <label>
    <RadioGroup.ItemHiddenInput />
    <RadioGroup.ItemText>
      <RadioGroup.ItemControl />
    </RadioGroup.ItemText>
  </label>
</RadioGroup.Item>

Hidden Input

The RadioGroup.ItemHiddenInput component renders a hidden HTML input element that enables proper form submission and integration with native form behaviors. This component is essential for the radio group to function correctly as it:

Provides the underlying input element that browsers use for form submission
Enables integration with form libraries and validation systems
Ensures the radio group works with native form reset functionality

// INCORRECT usage ❌
<RadioGroup.Item>
  <RadioGroup.ItemText>
    <RadioGroup.ItemControl />
  </RadioGroup.ItemText>
</RadioGroup.Item>

// CORRECT usage ✅
<RadioGroup.Item>
  <RadioGroup.ItemHiddenInput />
  <RadioGroup.ItemText>
    <RadioGroup.ItemControl />
  </RadioGroup.ItemText>
</RadioGroup.Item>

API Reference

Props

Root

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`defaultValue`		`string` The initial value of the checked radio when rendered. Use when you don't need to control the value of the radio group.
`disabled`		`boolean` If `true`, the radio group will be disabled
`form`		`string` The associate form of the underlying input.
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ root: string label: string indicator: string item: (value: string) => string itemLabel: (value: string) => string itemControl: (value: string) => string itemHiddenInput: (value: string) => string }>` The ids of the elements in the radio. Useful for composition.
`name`		`string` The name of the input fields in the radio (Useful for form submission).
`onValueChange`		`(details: ValueChangeDetails) => void` Function called once a radio is checked
`orientation`		`'horizontal' \| 'vertical'` Orientation of the radio group
`readOnly`		`boolean` Whether the checkbox is read-only
`value`		`string` The controlled value of the radio group

Attribute	Description
`[data-scope]`	radio-group
`[data-part]`	root
`[data-orientation]`	The orientation of the radio-group
`[data-disabled]`	Present when disabled

Indicator

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	radio-group
`[data-part]`	indicator
`[data-disabled]`	Present when disabled
`[data-orientation]`	The orientation of the indicator

CSS Variable	Description
`--transition-property`	The transition property value for the Indicator
`--left`	The left position value
`--top`	The top position value
`--width`	The width of the element
`--height`	The height of the element

ItemControl

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	radio-group
`[data-part]`	item-control
`[data-active]`	Present when active or pressed

ItemHiddenInput

Renders a <input> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Item

Renders a <label> element.

Prop	Default	Type
`value`		`string`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`disabled`		`boolean`
`invalid`		`boolean`

ItemText

Renders a <span> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Label

Renders a <label> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	radio-group
`[data-part]`	label
`[data-orientation]`	The orientation of the label
`[data-disabled]`	Present when disabled

RootProvider

Renders a <div> element.

Prop	Default	Type
`value`		`UseRadioGroupReturn`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Context

API

Property	Type
`value`	`string` The current value of the radio group
`setValue`	`(value: string) => void` Function to set the value of the radio group
`clearValue`	`VoidFunction` Function to clear the value of the radio group
`focus`	`VoidFunction` Function to focus the radio group
`getItemState`	`(props: ItemProps) => ItemState` Returns the state details of a radio input

Accessibility

Complies with the Radio WAI-ARIA design pattern.

Keyboard Support

Key	Description
`Tab`	Moves focus to either the checked radio item or the first radio item in the group.
`Space`	When focus is on an unchecked radio item, checks it.
`ArrowDown`	Moves focus and checks the next radio item in the group.
`ArrowRight`	Moves focus and checks the next radio item in the group.
`ArrowUp`	Moves focus to the previous radio item in the group.
`ArrowLeft`	Moves focus to the previous radio item in the group.