rapidUI

Radio Group

Set of mutually exclusive options built on Base UI Radio Group.

Installation

pnpm dlx shadcn@latest add https://rdf.dev.360online.com/r/radio-group.json

Installs to @/components/ui/radio-group.

Manual installation

Install the dependencies:

pnpm add @base-ui/react@^1.8.0

Copy the source into your project:

components/ui/radio-group.tsx
'use client'

import { Radio as RadioPrimitive } from '@base-ui/react/radio'
import { RadioGroup as RadioGroupPrimitive } from '@base-ui/react/radio-group'
import { cn } from '@/lib/utils'

/**
 * `readOnly` shows the value but prevents changing it. Unlike `disabled`, the items stay focusable and the group is
 * announced as read-only (`aria-readonly`). Base UI blocks the change and sets `data-readonly` on the group and items;
 * we also keep `data-read-only` on the group.
 */
function RadioGroup({ className, readOnly, ...props }: RadioGroupPrimitive.Props) {
	return (
		<RadioGroupPrimitive
			data-slot="radio-group"
			data-read-only={readOnly || undefined}
			readOnly={readOnly}
			className={cn('group/radio-group grid w-full gap-2', className)}
			{...props}
		/>
	)
}

function RadioGroupItem({ className, ...props }: RadioPrimitive.Root.Props) {
	return (
		<RadioPrimitive.Root
			data-slot="radio-group-item"
			className={cn(
				'group/radio-group-item peer relative flex aspect-square size-4 shrink-0 rounded-full border border-input text-primary outline-none group-has-[:focus-visible]/field-label:ring-0 group-has-[:focus-visible]/field-label:not-data-checked:border-input after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring data-disabled:cursor-not-allowed data-disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 aria-invalid:aria-checked:border-primary dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:border-primary data-checked:bg-primary group-has-[:focus-visible]/field-label:data-checked:border-primary data-readonly:cursor-default data-readonly:border-dashed data-readonly:border-foreground/60 data-readonly:bg-muted/50 data-readonly:data-checked:border-foreground/60 data-readonly:data-checked:bg-muted/50',
				className,
			)}
			{...props}
		>
			<RadioPrimitive.Indicator data-slot="radio-group-indicator" className="flex size-4 items-center justify-center">
				<span className="absolute top-1/2 left-1/2 size-2 -translate-x-1/2 -translate-y-1/2 rounded-full bg-primary-foreground group-data-readonly/radio-group-item:bg-foreground" />
			</RadioPrimitive.Indicator>
		</RadioPrimitive.Root>
	)
}

export { RadioGroup, RadioGroupItem }

A set of checkable buttons, known as radio buttons, where no more than one can be checked at a time. Built on top of Base UI Radio Group, it follows WAI-ARIA design patterns and is fully accessible.

Features

  • Controlled (value / onValueChange) and uncontrolled (defaultValue) modes
  • Disable the whole group or individual items
  • Invalid state via aria-invalid on the items
  • Enlarged hit area around the 16px radio for easier clicking
  • Works with Label or the Field components, including selectable choice cards
  • Keyboard navigation with the arrow keys (all four arrow keys move between options)
  • Screen reader support

Pass readOnly on RadioGroup to show a value that can't be changed. Unlike disabled, the items stay focusable and the group is announced as read-only (aria-readonly).

Usage

import { RadioGroup, RadioGroupItem } from '@/components/ui/radio-group'
import { Label } from '@/components/ui/label'

export function DeliveryMethod() {
  return (
    <RadioGroup defaultValue="mailbox">
      <div className="flex items-center gap-3">
        <RadioGroupItem value="mailbox" id="mailbox" />
        <Label htmlFor="mailbox">Digital mailbox</Label>
      </div>
      <div className="flex items-center gap-3">
        <RadioGroupItem value="letter" id="letter" />
        <Label htmlFor="letter">Letter</Label>
      </div>
    </RadioGroup>
  )
}

Choice Card

Wrap a horizontal Field in a FieldLabel to make the whole card selectable. The card is highlighted when its item is checked.

import { Field, FieldContent, FieldDescription, FieldLabel, FieldTitle } from '@/components/ui/field'
import { RadioGroup, RadioGroupItem } from '@/components/ui/radio-group'

<RadioGroup defaultValue="resident">
  <FieldLabel htmlFor="permit-resident">
    <Field orientation="horizontal">
      <RadioGroupItem value="resident" id="permit-resident" />
      <FieldContent>
        <FieldTitle>Resident parking</FieldTitle>
        <FieldDescription>Park in your own zone near home.</FieldDescription>
      </FieldContent>
    </Field>
  </FieldLabel>
</RadioGroup>

Examples

Default

Choosing how a decision is delivered. Wrap the group in a FieldSet with a FieldLegend so it has an accessible name.

With Descriptions

Waste collection frequencies with prices in the description.

Choice Card

Parking permit types as selectable cards.

Horizontal Layout

The group is a vertical grid by default. Use className for a horizontal layout; all four arrow keys move between options in any layout.

Disabled State

Disable the whole group with disabled on RadioGroup, or a single option with disabled on RadioGroupItem, and explain why.

Read Only

A decided care level, shown without letting it change by mouse or keyboard.

Invalid

A required question with aria-invalid on the items and an error linked with aria-describedby.

Accessibility

The RadioGroup component follows WAI-ARIA guidelines for radio groups:

  • Uses proper ARIA roles (radiogroup, radio)
  • Supports keyboard navigation:
    • Tab: Move focus to the radio group
    • Space: Select the focused radio button
    • Arrow keys: Navigate between radio buttons
  • Provides proper labeling and descriptions
  • Maintains focus management

Best Practices

  • Always provide labels for radio options
  • Use meaningful values for radio options
  • Consider using descriptions for complex choices
  • Group related options together
  • Use appropriate spacing between options
  • Provide clear visual feedback for selected state
  • Checkbox
  • Select
  • Switch
  • Field