Radio Group

A set of checkable buttons, known as radio buttons, where no more than one of the buttons can be checked at a time.

Import

ts
import { RadioGroup } from "@kobalte/core";

ts
import { RadioGroup } from "@kobalte/core";

Features

Follow the WAI ARIA Radio Group design pattern.
Each radio is built with a native HTML <input> element, which is visually hidden to allow custom styling.
Syncs with form reset events.
Group and radio labeling support for assistive technology.
Can be controlled or uncontrolled.

Anatomy

The radio group consists of:

RadioGroup.Root: The root container for the radio group.
RadioGroup.Label: The label that gives the user information on the radio group.
RadioGroup.Description: The description that gives the user more information on the radio group.
RadioGroup.ErrorMessage: The error message that gives the user information about how to fix a validation error on the radio group.

The radio item consists of:

RadioGroup.Item: The root container for a radio button.
RadioGroup.ItemInput: The native html input that is visually hidden in the radio button.
RadioGroup.ItemControl: The element that visually represents a radio button.
RadioGroup.ItemIndicator: The visual indicator rendered when the radio button is in a checked state.
RadioGroup.ItemLabel: The label that gives the user information on the radio button.
RadioGroup.ItemDescription: The description that gives the user more information on the radio button.

tsx
<RadioGroup.Root>
	<RadioGroup.Label />
	<RadioGroup.Item>
		<RadioGroup.ItemInput />
		<RadioGroup.ItemControl>
			<RadioGroup.ItemIndicator />
		</RadioGroup.ItemControl>
		<RadioGroup.ItemLabel />
		<RadioGroup.ItemDescription />
	</RadioGroup.Item>
	<RadioGroup.Description />
	<RadioGroup.ErrorMessage />
</RadioGroup.Root>

tsx
<RadioGroup.Root>
	<RadioGroup.Label />
	<RadioGroup.Item>
		<RadioGroup.ItemInput />
		<RadioGroup.ItemControl>
			<RadioGroup.ItemIndicator />
		</RadioGroup.ItemControl>
		<RadioGroup.ItemLabel />
		<RadioGroup.ItemDescription />
	</RadioGroup.Item>
	<RadioGroup.Description />
	<RadioGroup.ErrorMessage />
</RadioGroup.Root>

Example

Favorite fruit

Apple

Orange

Watermelon

Usage

Default value

An initial, uncontrolled value can be provided using the defaultValue prop, which accepts a value corresponding with the value prop of each radio.

Favorite fruit

Apple

Orange

Watermelon

tsx
<RadioGroup.Root defaultValue="Orange">
	<RadioGroup.Label>Favorite fruit</RadioGroup.Label>
	<div>
		<For each={["Apple", "Orange", "Watermelon"]}>
			{fruit => <RadioGroup.Item value={fruit}>...</RadioGroup.Item>}
		</For>
	</div>
</RadioGroup.Root>

tsx
<RadioGroup.Root defaultValue="Orange">
	<RadioGroup.Label>Favorite fruit</RadioGroup.Label>
	<div>
		<For each={["Apple", "Orange", "Watermelon"]}>
			{fruit => <RadioGroup.Item value={fruit}>...</RadioGroup.Item>}
		</For>
	</div>
</RadioGroup.Root>

Controlled value

The value prop, which accepts a value corresponding with the value prop of each radio, can be used to make the value controlled. The onChange event is fired when the user selects a radio, and receives the new value.

Favorite fruit

Apple

Orange

Watermelon

Your favorite fruit is: Orange.

tsx
import { createSignal } from "solid-js";
function ControlledExample() {
	const [value, setValue] = createSignal("Orange");
	return (
		<>
			<RadioGroup.Root value={value()} onChange={setValue}>
				<RadioGroup.Label>Favorite fruit</RadioGroup.Label>
				<div>
					<For each={["Apple", "Orange", "Watermelon"]}>
						{fruit => <RadioGroup.Item value={fruit}>...</RadioGroup.Item>}
					</For>
				</div>
			</RadioGroup.Root>
			<p>Your favorite fruit is: {value()}.</p>
		</>
	);
}

tsx
import { createSignal } from "solid-js";
function ControlledExample() {
	const [value, setValue] = createSignal("Orange");
	return (
		<>
			<RadioGroup.Root value={value()} onChange={setValue}>
				<RadioGroup.Label>Favorite fruit</RadioGroup.Label>
				<div>
					<For each={["Apple", "Orange", "Watermelon"]}>
						{fruit => <RadioGroup.Item value={fruit}>...</RadioGroup.Item>}
					</For>
				</div>
			</RadioGroup.Root>
			<p>Your favorite fruit is: {value()}.</p>
		</>
	);
}

Description

The RadioGroup.Description component can be used to associate additional help text with a radio group.

Favorite fruit

Apple

Orange

Watermelon

Choose the fruit you like the most.

tsx
<RadioGroup.Root>
	<RadioGroup.Label>Favorite fruit</RadioGroup.Label>
	<div>
		<For each={["Apple", "Orange", "Watermelon"]}>
			{fruit => <RadioGroup.Item value={fruit}>...</RadioGroup.Item>}
		</For>
	</div>
	<RadioGroup.Description>Choose the fruit you like the most.</RadioGroup.Description>
</RadioGroup.Root>

tsx
<RadioGroup.Root>
	<RadioGroup.Label>Favorite fruit</RadioGroup.Label>
	<div>
		<For each={["Apple", "Orange", "Watermelon"]}>
			{fruit => <RadioGroup.Item value={fruit}>...</RadioGroup.Item>}
		</For>
	</div>
	<RadioGroup.Description>Choose the fruit you like the most.</RadioGroup.Description>
</RadioGroup.Root>

Error message

The RadioGroup.ErrorMessage component can be used to help the user fix a validation error. It should be combined with the validationState prop to semantically mark the radio group as invalid for assistive technologies.

By default, it will render only when the validationState prop is set to invalid, use the forceMount prop to always render the error message (ex: for usage with animation libraries).

Favorite fruit

Apple

Orange

Watermelon

Hmm, I prefer apples.

tsx
import { createSignal } from "solid-js";
function ErrorMessageExample() {
	const [value, setValue] = createSignal("Orange");
	return (
		<RadioGroup.Root
			value={value()}
			onChange={setValue}
			validationState={value() !== "Apple" ? "invalid" : "valid"}
		>
			<RadioGroup.Label>Favorite fruit</RadioGroup.Label>
			<div>
				<For each={["Apple", "Orange", "Watermelon"]}>
					{fruit => <RadioGroup.Item value={fruit}>...</RadioGroup.Item>}
				</For>
			</div>
			<RadioGroup.ErrorMessage>Hmm, I prefer apples.</RadioGroup.ErrorMessage>
		</RadioGroup.Root>
	);
}

tsx
import { createSignal } from "solid-js";
function ErrorMessageExample() {
	const [value, setValue] = createSignal("Orange");
	return (
		<RadioGroup.Root
			value={value()}
			onChange={setValue}
			validationState={value() !== "Apple" ? "invalid" : "valid"}
		>
			<RadioGroup.Label>Favorite fruit</RadioGroup.Label>
			<div>
				<For each={["Apple", "Orange", "Watermelon"]}>
					{fruit => <RadioGroup.Item value={fruit}>...</RadioGroup.Item>}
				</For>
			</div>
			<RadioGroup.ErrorMessage>Hmm, I prefer apples.</RadioGroup.ErrorMessage>
		</RadioGroup.Root>
	);
}

HTML forms

The radio group name prop, paired with the radio value prop, can be used for integration with HTML forms.

tsx
function HTMLFormExample() {
	const onSubmit = (e: SubmitEvent) => {
		// handle form submission.
	};
	return (
		<form onSubmit={onSubmit}>
			<RadioGroup.Root name="favorite-fruit">
				<RadioGroup.Label>Favorite fruit</RadioGroup.Label>
				<div>
					<For each={["Apple", "Orange", "Watermelon"]}>
						{fruit => <RadioGroup.Item value={fruit}>...</RadioGroup.Item>}
					</For>
				</div>
			</RadioGroup.Root>
			<div>
				<button type="reset">Reset</button>
				<button type="submit">Submit</button>
			</div>
		</form>
	);
}

tsx
function HTMLFormExample() {
	const onSubmit = (e: SubmitEvent) => {
		// handle form submission.
	};
	return (
		<form onSubmit={onSubmit}>
			<RadioGroup.Root name="favorite-fruit">
				<RadioGroup.Label>Favorite fruit</RadioGroup.Label>
				<div>
					<For each={["Apple", "Orange", "Watermelon"]}>
						{fruit => <RadioGroup.Item value={fruit}>...</RadioGroup.Item>}
					</For>
				</div>
			</RadioGroup.Root>
			<div>
				<button type="reset">Reset</button>
				<button type="submit">Submit</button>
			</div>
		</form>
	);
}

API Reference

RadioGroup.Root

Prop	Description
value	`string` The controlled value of the radio button to check.
defaultValue	`string` The value of the radio button that should be checked when initially rendered. Useful when you do not need to control the state of the radio buttons.
onChange	`(value: string) => void` Event handler called when the value changes.
orientation	`'horizontal' \| 'vertical'` The axis the radio group items should align with.
name	`string` The name of the radio group. Submitted with its owning form as part of a name/value pair.
validationState	`'valid' \| 'invalid'` Whether the radio group should display its "valid" or "invalid" visual styling.
required	`boolean` Whether the user must check a radio group item before the owning form can be submitted.
disabled	`boolean` Whether the radio group is disabled.
readOnly	`boolean` Whether the radio group items can be selected but not changed by the user.

Data attribute	Description
data-valid	Present when the radio group is valid according to the validation rules.
data-invalid	Present when the radio group is invalid according to the validation rules.
data-required	Present when the user must check a radio group item before the owning form can be submitted.
data-disabled	Present when the radio group is disabled.
data-readonly	Present when the radio group is read only.

RadioGroup.Label, RadioGroup.Description and RadioGroup.ErrorMesssage shares the same data-attributes.

RadioGroup.ErrorMessage

Prop	Description
forceMount	`boolean` Used to force mounting when more control is needed. Useful when controlling animation with SolidJS animation libraries.

RadioGroup.Item

Prop	Description
value	`string` The value of the radio button, used when submitting an HTML form. See MDN.
disabled	`boolean` Whether the radio button is disabled or not.

Data attribute	Description
data-valid	Present when the parent radio group is valid according to the validation rules.
data-invalid	Present when the parent radio group is invalid according to the validation rules.
data-checked	Present when the radio is checked.
data-disabled	Present when the radio is disabled.

RadioGroup.ItemInput, RadioGroup.ItemControl, RadioGroup.ItemIndicator and RadioGroup.ItemLabel shares the same data-attributes.

RadioGroup.ItemIndicator

Prop	Description
forceMount	`boolean` Used to force mounting when more control is needed. Useful when controlling animation with SolidJS animation libraries.

Rendered elements

Component	Default rendered element
`RadioGroup.Root`	`div`
`RadioGroup.Label`	`span`
`RadioGroup.Description`	`div`
`RadioGroup.ErrorMessage`	`div`
`RadioGroup.Item`	`div`
`RadioGroup.ItemInput`	`input`
`RadioGroup.ItemControl`	`div`
`RadioGroup.ItemIndicator`	`div`
`RadioGroup.ItemLabel`	`label`
`RadioGroup.ItemDescription`	`div`

Accessibility

Keyboard Interactions

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