@biem/ui

Radio Group

A set of options that lets users select exactly one.

A radio group lets users select exactly one option from a set. Selecting an item clears the selection before it, so the group never holds more than one value. Each item has a label that names its option, and a click on the label selects the item just as a click on the item does.

Usage

radio-group-default.tsx
import { Field, FieldLabel } from "@biem/ui/components/ui/field";
import { RadioGroup, RadioGroupItem } from "@biem/ui/components/ui/radio-group";

export function RadioGroupDefault() {
	return (
		<div className="w-full max-w-sm">
			<RadioGroup aria-label="Shipping method">
				<Field orientation="horizontal">
					<RadioGroupItem id="shipping-scheduled-truck" value="scheduled-truck"/>
					<FieldLabel htmlFor="shipping-scheduled-truck">Scheduled truck</FieldLabel>
				</Field>
				<Field orientation="horizontal">
					<RadioGroupItem id="shipping-courier" value="courier"/>
					<FieldLabel htmlFor="shipping-courier">Courier</FieldLabel>
				</Field>
				<Field orientation="horizontal">
					<RadioGroupItem id="shipping-store-pickup" value="store-pickup"/>
					<FieldLabel htmlFor="shipping-store-pickup">Store pickup</FieldLabel>
				</Field>
			</RadioGroup>
		</div>
	);
}

Examples

Default Value

Many choices have an option that fits most cases, such as the standard payment terms of a supplier. Through defaultValue, the radio group starts with that option selected, and users change it only when their case differs.

Controlled

Sometimes the selection depends on more than a click, for example a choice restored from saved settings or one that decides which fields a form shows next. With value and onValueChange, the application holds the selection itself, so the radio group reflects choices made elsewhere and the rest of the interface can respond to every change.

Disabled

A decision can become fixed for a while, for example once an order has been released to a supplier. Set on the group, disabled keeps every option in view, prevents users from selecting any of them and exposes this state to assistive technology. Its value is then left out when the form is submitted.

Disabled Item

Within an otherwise open choice, one option can be unavailable, such as a return to the supplier for perishable goods. Marked as disabled, that item can no longer be selected and exposes its state to assistive technology, while users choose freely among the remaining options.

Invalid

Some forms cannot be completed without a choice, and users need to see at once where that choice is still missing. When validation fails, aria-invalid on each item marks the choice as invalid, on screen as well as for assistive technology.

API Reference

RadioGroup

Propvalue
Typeany
Default–
DescriptionSets the value of the selected item and makes the radio group controlled. Update it in onValueChange.
PropdefaultValue
Typeany
Default–
DescriptionSets the value of the item that is selected at first render. The radio group then tracks the selection itself.
ProponValueChange
Type(value: any, eventDetails: RadioGroupChangeEventDetails) => void
Default–
DescriptionRuns when users select an item. It receives the value of that item.
Propdisabled
Typeboolean
Defaultfalse
DescriptionPrevents users from selecting any item and exposes the disabled state to assistive technology. A disabled radio group submits no value with the form.
PropreadOnly
Typeboolean
Defaultfalse
DescriptionPrevents users from selecting a different item. Unlike a disabled radio group, it submits its value with the form.
Proprequired
Typeboolean
Defaultfalse
DescriptionRequires users to select an item before they can submit the form.
Propname
Typestring
Default–
DescriptionIdentifies the radio group when the form is submitted.
Propform
Typestring
Default–
DescriptionSets the ID of the form that the radio group belongs to. Set it when the radio group is rendered outside of that form.
PropinputRef
TypeRef<HTMLInputElement>
Default–
DescriptionReceives the hidden input element of the selected item. While no item is selected, it receives the hidden input of the first item that is not disabled.
Proprender
TypeReactElement | render function
Default–
DescriptionReplaces the native element or composes the radio group with another component.

RadioGroupItem

Propvalue
Typeany
Default–
DescriptionIdentifies the item in value, defaultValue and onValueChange of the radio group. The selected item submits it with the form. Every item needs one.
Propid
Typestring
Default–
DescriptionSets the ID of the hidden input, so that a label can refer to the item with htmlFor. With nativeButton, the ID goes to the rendered button instead.
Propdisabled
Typeboolean
Defaultfalse
DescriptionPrevents users from selecting the item and exposes the disabled state to assistive technology. A disabled radio group disables the item as well.
PropreadOnly
Typeboolean
Defaultfalse
DescriptionPrevents users from selecting the item. A read-only radio group makes the item read-only as well.
Proprequired
Typeboolean
Defaultfalse
DescriptionMarks the hidden input of the item as required for the validation of the form. A required radio group makes the item required as well.
PropinputRef
TypeRef<HTMLInputElement>
Default–
DescriptionReceives the hidden input element that carries the value of the item in a form.
Proprender
TypeReactElement | render function
Default–
DescriptionReplaces the native element or composes the item with another component.
PropnativeButton
Typeboolean
Defaultfalse
DescriptionDeclares whether the rendered element is a native button. Set it to true when render returns a button.

On this page

IntroductionUsageExamplesDefault ValueControlledDisabledDisabled ItemInvalidAPI ReferenceRadioGroupRadioGroupItem