RadioGroup Component

The RadioGroup component is a fully accessible and highly customizable selection control built with TypeScript and Tailwind CSS. It allows users to select a single option from a list with full keyboard navigation, rich content support, and complete styling flexibility.

Use selectedValue and onChange for controlled state, orientation for layout direction, and size for consistent scaling. You can also enhance options with icon and description for better UX clarity.

Option Structure

Pass an options array with string labels and values. Descriptions, icons, and per-option disabled states are optional.

1type RadioOption = {
2  label: string;
3  value: string;
4  description?: string;
5  icon?: React.ReactNode;
6  disabled?: boolean;
7};

Import Component From Library

javascript

1import { RadioGroup } from "@neuctra/ui";

Basic Usage Code

Start with a simple radio group. The component supports single selection with keyboard navigation, icons, and descriptions.

jsx

1import { useState } from 'react';
2import { RadioGroup } from '@neuctra/ui';
3
4function BasicExample() {
5  const [value, setValue] = useState('option1');
6
7  const options = [
8    { label: 'Option One', value: 'option1' },
9    { label: 'Option Two', value: 'option2' },
10    { label: 'Option Three', value: 'option3' }
11  ];
12
13  return (
14    <RadioGroup
15      name="example"
16      options={options}
17      selectedValue={value}
18      onChange={setValue}
19    />
20  );
21}

What It Does

Single Selection: Only one option can be selected at a time.

Keyboard Navigation: Arrow keys, Home/End, Space/Enter support.

Multiple Sizes: Small, medium, and large variants.

Flexible Layout: Vertical or horizontal orientation.

Rich Content: Support for icons, descriptions, and custom styling.

Fully Accessible: ARIA attributes, screen reader support, focus management.

Basic Usage

Create a simple radio group with options array. Each option needs a label and value.

Option One

This is the first option

Option Two

This is the second option

Option Three

This is the third option

Rich Content Support

Add icons and descriptions to make options more informative and visually appealing.

Light Mode

Bright and clear

Dark Mode

Easy on the eyes

Auto Mode

Follows system

Sizes

Choose from three size variants: sm, md (default), and lg.

Small (sm)

Option One

This is the first option

Option Two

This is the second option

Option Three

This is the third option

Medium (md) - Default

Option One

This is the first option

Option Two

This is the second option

Option Three

This is the third option

Large (lg)

Option One

This is the first option

Option Two

This is the second option

Option Three

This is the third option

Orientation

Display options vertically (default) or horizontally using the orientation prop.

Vertical (default)

Option One

This is the first option

Option Two

This is the second option

Option Three

This is the third option

Horizontal

Option One

This is the first option

Option Two

This is the second option

Option Three

This is the third option

States & Validation

Handle disabled options, read-only mode, required fields, and error states.

Enabled Option

Disabled Option

Another Enabled

Please select an option

Keyboard Navigation

Full keyboard support for accessibility and power users.

Navigation:

↑ ↓ Move up/down
← → Move left/right
Home First option
End Last option

Selection:

Space Select focused option
Enter Select focused option
Tab Move to next focusable element

Option One

This is the first option

Option Two

This is the second option

Option Three

This is the third option

Styling & Customization

RadioGroup supports multiple styling layers so you can fully customize layout, structure, and selection state using Tailwind CSS classes.

Option One

This is the first option

Option Two

This is the second option

Option Three

This is the third option

Props Table

All available props for the RadioGroup component.

Prop	Type	Default	Description
name	string	—	Form field name for native radio grouping.
options	Option[]	required	List of radio options (label, value, description, icon, disabled).
selectedValue	string	—	Currently selected option value.
onChange	(value: string) => void	—	Triggered when selection changes.
disabled	boolean	false	Disables all options.
readOnly	boolean	false	Prevents interaction but keeps UI active.
required	boolean	false	Marks field as required for forms.
error	string	—	Error message below component.
size	"sm" \| "md" \| "lg"	"md"	Controls radio size.
orientation	"vertical" \| "horizontal"	"vertical"	Layout direction.
animationDuration	number	0.2	Dot animation speed in seconds.
className	string	—	Root container styles.
itemClassName	string	—	Each radio item wrapper.
labelClassName	string	—	Label text styling.
descriptionClassName	string	—	Description text styling.
iconWrapperClassName	string	—	Icon container styling.
indicatorClassName	string	—	Outer radio circle styling.
dotClassName	string	—	Inner selected dot styling.
errorClassName	string	—	Error message styling.
style	React.CSSProperties	—	Root inline styles.
itemStyle	React.CSSProperties	—	Item inline styles.
labelStyle	React.CSSProperties	—	Label inline styles.
descriptionStyle	React.CSSProperties	—	Description inline styles.
iconWrapperStyle	React.CSSProperties	—	Icon wrapper inline styles.
indicatorStyle	React.CSSProperties	—	Radio indicator inline styles.
dotStyle	React.CSSProperties	—	Dot inline styles.
errorStyle	React.CSSProperties	—	Error message inline styles.

Common Mistakes

<RadioGroup selectedValue="one" />

options array is required.

<RadioGroup selectedValue="one" />

Without onChange, selection will not update.

<RadioGroup label="Choose one" />

RadioGroup does not have a group label prop. Render your own label text above the component when needed.

<RadioGroup options={options} selectedValue={value} onChange={setValue} />

Proper controlled usage.

Pro Tips

Use orientation="horizontal" for ratings, pricing, or quick choices.
Add icon + description to improve decision clarity.
Keep selectedValue controlled for predictable UI state.
Use readOnly instead of disabling for preview modes.
Use keyboard navigation — it's already built in (Arrow keys, Enter, Space).
Prefer Tailwind via className props instead of inline styles for scalability.
Skip disabled options automatically — no extra logic needed.

Frequently Asked Questions

How do I install and import the RadioGroup component?

Install the @neuctra/ui package, then import it with: import { RadioGroup } from "@neuctra/ui";

What variants and sizes does RadioGroup support?

RadioGroup supports sizes: sm, md, lg. Use the variant and size props to switch between them, or pass a className to layer on custom Tailwind CSS classes.

Is the RadioGroup component accessible?

RadioGroup is built with semantic HTML and standard ARIA attributes, and supports keyboard navigation and focus states out of the box, so it works well with screen readers and keyboard-only users.