RadioGroup Primitive

Headless, unstyled radio group primitive with full keyboard navigation and accessibility.

Basic Headless Primitive

The primitive provides behavior, accessibility, and arrow key navigation.

Option 1

Option 2

Option 3

Selected: Option 1

Try using arrow keys ↑↓ to navigate!

Controlled State

Control the primitive state externally with buttons.

Small

Medium

Large

Selected size: Medium

Arrow Key Navigation

Built-in keyboard navigation with arrow keys.

North

East

South

West

Click an option, then use ↑↓ or ←→ arrow keys to navigate

Disabled State

Disable the entire group or individual items.

Disabled Group:

Option A

Option B

Accessibility Features

Built-in accessibility features following WAI-ARIA design patterns.

✓ ARIA attributes: role="radiogroup" and role="radio", aria-checked, aria-disabled automatically applied

✓ Arrow key navigation: ↑↓←→ keys navigate between options and auto-select

✓ Keyboard support: Space and Enter keys work out of the box

✓ Screen reader support: Proper role announcements and state changes

✓ Focus management: Roving tab index pattern built-in

✓ Disabled state: Proper disabled attribute and behavior for group and individual items

Keyboard Shortcuts

Navigate and interact with radio groups using keyboard.

Navigate options Arrow Keys

Select option Space / Enter

Navigate to group Tab

API Reference

Component properties and parameters.

RadioGroup<TValue>

Value

Type: TValue?
The currently selected value. Supports two-way binding.

ValueChanged

Type: EventCallback<TValue>
Callback invoked when the selected value changes.

Disabled

Type: bool
Default: false
Disables the entire radio group when true.

AriaLabel

Type: string?
Accessible label for screen readers.

RadioGroupItem<TValue>

Value

Type: TValue (required)
The value of this radio item.

Disabled

Type: bool
Default: false
Disables this individual radio item when true.

Additional Attributes

Any additional attributes (class, style, Id, AriaLabel, etc.) are passed to the button element.

Auto-applied attributes: data-state, aria-checked, disabled, tabindex

When to Use Primitives

Choose between primitives and styled components based on your needs.

Use RadioGroup Primitive

✓ Building a custom design system
✓ Need complete control over styling
✓ Want to apply your own CSS framework
✓ Creating unique visual designs

Use Styled Component

● Want shadcn/ui design out of the box
● Need quick implementation
● Like the default styling
● Prefer convention over configuration