Radio

Single choice selection component for mutually exclusive options with proper grouping support.

Basic Usage

Choose your plan:

Free Plan

Basic Plan

Premium Plan

Enterprise Plan

Selected: basic

import { useState } from 'react'
import { Radio, RadioGroup } from '@akitectio/aki-ui'

function BasicRadio() {
  const [selectedPlan, setSelectedPlan] = useState('basic')

  return (
    <div>
      <h3>Choose your plan:</h3>
      <RadioGroup name="plan" value={selectedPlan} onChange={setSelectedPlan}>
        <Radio value="free" label="Free Plan" />
        <Radio value="basic" label="Basic Plan" />
        <Radio value="premium" label="Premium Plan" />
        <Radio value="enterprise" label="Enterprise Plan" />
      </RadioGroup>
      <p>Selected: {selectedPlan}</p>
    </div>
  )
}

Individual Radio Buttons

Select a size:

Small

Medium

Large

Selected size: None

import { useState } from 'react'
import { Radio } from '@akitectio/aki-ui'

function IndividualRadio() {
  const [selectedSize, setSelectedSize] = useState('')

  return (
    <div>
      <h3>Select a size:</h3>
      <div className="space-y-2">
        <Radio
          name="size"
          value="small"
          label="Small"
          checked={selectedSize === 'small'}
          onChange={() => setSelectedSize('small')}
        />
        <Radio
          name="size"
          value="medium"
          label="Medium"
          checked={selectedSize === 'medium'}
          onChange={() => setSelectedSize('medium')}
        />
        <Radio
          name="size"
          value="large"
          label="Large"
          checked={selectedSize === 'large'}
          onChange={() => setSelectedSize('large')}
        />
      </div>
    </div>
  )
}

Colors

<div className="grid grid-cols-2 md:grid-cols-3 gap-4">
  <Radio name="colors" value="primary" label="Primary" color="primary" />
  <Radio name="colors" value="secondary" label="Secondary" color="secondary" />
  <Radio name="colors" value="success" label="Success" color="success" />
  <Radio name="colors" value="danger" label="Danger" color="danger" />
  <Radio name="colors" value="warning" label="Warning" color="warning" />
  <Radio name="colors" value="info" label="Info" color="info" />
</div>

Sizes

Small radio button

Medium radio button

Large radio button

<div className="space-y-4">
  <Radio name="sizes" value="sm" label="Small radio button" size="sm" />
  <Radio name="sizes" value="md" label="Medium radio button" size="md" />
  <Radio name="sizes" value="lg" label="Large radio button" size="lg" />
</div>

States

Normal state

Checked state

Disabled state

Disabled checked

<div className="space-y-4">
  <Radio name="states" value="normal" label="Normal state" />
  <Radio name="states" value="checked" label="Checked state" defaultChecked />
  <Radio name="states" value="disabled" label="Disabled state" disabled />
  <Radio name="states" value="disabled-checked" label="Disabled checked" disabled checked />
</div>

With Helper Text

Option with helper text

This option provides additional features

Invalid option

Please select a valid option

Required option

This option is required for activation

<div className="space-y-4">
  <Radio
    name="helper"
    value="option1"
    label="Option with helper text"
    helperText="This option provides additional features"
  />
  <Radio
    name="helper"
    value="option2"
    label="Invalid option"
    isInvalid
    errorMessage="Please select a valid option"
  />
  <Radio
    name="helper"
    value="option3"
    label="Required option"
    required
  />
</div>

Label Position

Label on the right (default)

Label on the left

<div className="space-y-4">
  <Radio name="position" value="right" label="Label on the right (default)" />
  <Radio name="position" value="left" label="Label on the left" labelLeft />
</div>

API Reference

Radio Props

Prop	Type	Default	Description
label	React.ReactNode	-	The label for the radio button
checked	boolean	-	Whether the radio button is checked
defaultChecked	boolean	false	Default checked state (uncontrolled)
onChange	(checked: boolean) => void	-	Called when the checked state changes
disabled	boolean	false	Whether the radio button is disabled
color	'primary' \| 'secondary' \| 'success' \| 'danger' \| 'warning' \| 'info'	'primary'	The radio button color
size	'sm' \| 'md' \| 'lg'	'md'	The size of the radio button
value	string	-	The value of the radio button
name	string	-	The name of the radio button (essential for grouping)
labelLeft	boolean	false	Whether to render the label on the left side
helperText	string	-	Helper text to display below the radio button
errorMessage	string	-	Error message to display when invalid
isInvalid	boolean	false	Whether the radio button is invalid
required	boolean	false	Whether the radio button is required

RadioGroup Props

Prop	Type	Default	Description
children	React.ReactNode	-	Radio group children
name	string	-	Name for all radio buttons in the group
value	string	-	Currently selected value
onChange	(value: string) => void	-	Called when the selected value changes

Accessibility

✅ Full keyboard navigation support
✅ Screen reader compatible with proper ARIA attributes
✅ Supports focus management within radio groups
✅ High contrast mode support
✅ Proper labeling and grouping for assistive technologies

Keyboard Navigation

Arrow keys - Navigate between radio buttons in the same group
Space - Select the focused radio button
Tab - Move focus to next focusable element
Shift + Tab - Move focus to previous focusable element

Best Practices

✅ Do

Use radio buttons for mutually exclusive options
Always provide a name attribute for radio button groups
Use clear and descriptive labels
Group related radio buttons with RadioGroup
Provide a default selection when appropriate
Use helper text to clarify options

❌ Don't

Use radio buttons for multiple selections (use checkboxes instead)
Have only one radio button in a group
Use radio buttons for actions (use buttons instead)
Make labels too long or confusing
Forget to provide a way to deselect all options when appropriate