# RadioButton

A radio button component that allows users to select one option from a group of mutually exclusive choices. It provides flexible sizing, label positioning, and integrates seamlessly with form handling. RadioButton components are typically used in groups where only one selection is allowed.

## Aliases

- RadioButton
- Radio
- OptionButton

## Props Breakdown

**Extends:** `InputHTMLAttributes<HTMLInputElement>` (excluding `type`, `size`, `value`) + `ControlledFormComponentProps<string | number>`

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `children` | `ReactNode` | `undefined` | No | The label content of the radio button |
| `size` | `'Small' \| 'Medium' \| 'Large'` | `'Medium'` | No | The size of the radio button |
| `labelAlignment` | `'Left' \| 'Right'` | `'Right'` | No | Position of the label relative to the radio button |
| `initialValue` | `string \| number` | `undefined` | No | The initial value for the field |
| `checked` | `boolean` | `undefined` | No | Whether the radio button is checked |
| `value` | `string \| number` | `undefined` | No | The current value of the form field |
| `onValueChange` | `(value: string \| number) => void` | `undefined` | No | Callback function that is called when the field value changes |
| `disabled` | `boolean` | `false` | No | Whether the form field is disabled and cannot be interacted with |
| `required` | `boolean` | `false` | No | Whether the form field must have a value |
| `invalid` | `boolean` | `false` | No | Whether the form field's current value is invalid |
| `id` | `string` | `undefined` | No | Id for the form field |
| `name` | `string` | `undefined` | No | Name attribute for the radio button |

Plus all standard HTML input attributes (onChange, onFocus, onBlur, aria-*, data-*, etc.).

## Examples

### Basic Radio Button

```tsx
import { RadioButton } from '@delightui/components';

function BasicRadioButtonExample() {
  const [selectedOption, setSelectedOption] = useState('');

  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
      <RadioButton
        name="basicExample"
        value="option1"
        checked={selectedOption === 'option1'}
        onValueChange={setSelectedOption}
      >
        Option 1
      </RadioButton>
      
      <RadioButton
        name="basicExample"
        value="option2"
        checked={selectedOption === 'option2'}
        onValueChange={setSelectedOption}
      >
        Option 2
      </RadioButton>
      
      <RadioButton
        name="basicExample"
        value="option3"
        checked={selectedOption === 'option3'}
        onValueChange={setSelectedOption}
      >
        Option 3
      </RadioButton>
    </div>
  );
}
```

### Different Sizes

```tsx
import { RadioButton } from '@delightui/components';

function SizedRadioButtonExample() {
  const [selectedSize, setSelectedSize] = useState('medium');

  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
      <RadioButton
        name="sizeExample"
        value="small"
        size="Small"
        checked={selectedSize === 'small'}
        onValueChange={setSelectedSize}
      >
        Small Radio Button
      </RadioButton>
      
      <RadioButton
        name="sizeExample"
        value="medium"
        size="Medium"
        checked={selectedSize === 'medium'}
        onValueChange={setSelectedSize}
      >
        Medium Radio Button
      </RadioButton>
      
      <RadioButton
        name="sizeExample"
        value="large"
        size="Large"
        checked={selectedSize === 'large'}
        onValueChange={setSelectedSize}
      >
        Large Radio Button
      </RadioButton>
    </div>
  );
}
```

### Label Alignment

```tsx
import { RadioButton } from '@delightui/components';

function LabelAlignmentExample() {
  const [selectedAlignment, setSelectedAlignment] = useState('right');

  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
      <RadioButton
        name="alignmentExample"
        value="left"
        labelAlignment="Left"
        checked={selectedAlignment === 'left'}
        onValueChange={setSelectedAlignment}
      >
        Label on Left
      </RadioButton>
      
      <RadioButton
        name="alignmentExample"
        value="right"
        labelAlignment="Right"
        checked={selectedAlignment === 'right'}
        onValueChange={setSelectedAlignment}
      >
        Label on Right
      </RadioButton>
    </div>
  );
}
```

### Form Integration

```tsx
import { Form, FormField, RadioButton, Button } from '@delightui/components';

function RadioButtonFormExample() {
  const handleSubmit = (data: any) => {
    console.log('Form submitted:', data);
  };

  return (
    <Form onSubmit={handleSubmit}>
      <FormField
        name="paymentMethod"
        label="Payment Method"
        required
      >
        <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
          <RadioButton name="paymentMethod" value="credit-card">
            Credit Card
          </RadioButton>
          <RadioButton name="paymentMethod" value="paypal">
            PayPal
          </RadioButton>
          <RadioButton name="paymentMethod" value="bank-transfer">
            Bank Transfer
          </RadioButton>
        </div>
      </FormField>

      <FormField
        name="deliverySpeed"
        label="Delivery Speed"
        required
      >
        <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
          <RadioButton name="deliverySpeed" value="standard">
            Standard Delivery (5-7 days)
          </RadioButton>
          <RadioButton name="deliverySpeed" value="express">
            Express Delivery (2-3 days)
          </RadioButton>
          <RadioButton name="deliverySpeed" value="overnight">
            Overnight Delivery
          </RadioButton>
        </div>
      </FormField>

      <Button type="submit">
        Complete Order
      </Button>
    </Form>
  );
}
```

### Survey Example

```tsx
import { Form, FormField, RadioButton, Button, Text } from '@delightui/components';

function SurveyExample() {
  const handleSubmit = (data: any) => {
    console.log('Survey submitted:', data);
  };

  return (
    <Form onSubmit={handleSubmit}>
      <FormField
        name="satisfaction"
        label="How satisfied are you with our service?"
        required
      >
        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
          <RadioButton name="satisfaction" value="very-satisfied">
            Very Satisfied
          </RadioButton>
          <RadioButton name="satisfaction" value="satisfied">
            Satisfied
          </RadioButton>
          <RadioButton name="satisfaction" value="neutral">
            Neutral
          </RadioButton>
          <RadioButton name="satisfaction" value="dissatisfied">
            Dissatisfied
          </RadioButton>
          <RadioButton name="satisfaction" value="very-dissatisfied">
            Very Dissatisfied
          </RadioButton>
        </div>
      </FormField>

      <FormField
        name="recommendation"
        label="Would you recommend us to others?"
        required
      >
        <div style={{ display: 'flex', gap: '24px' }}>
          <RadioButton name="recommendation" value="yes">
            Yes
          </RadioButton>
          <RadioButton name="recommendation" value="no">
            No
          </RadioButton>
          <RadioButton name="recommendation" value="maybe">
            Maybe
          </RadioButton>
        </div>
      </FormField>

      <Button type="submit">
        Submit Survey
      </Button>
    </Form>
  );
}
```

### Disabled States

```tsx
import { RadioButton } from '@delightui/components';

function DisabledRadioButtonExample() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
      <RadioButton
        name="disabledExample"
        value="enabled"
        checked={true}
      >
        Enabled and Selected
      </RadioButton>
      
      <RadioButton
        name="disabledExample"
        value="disabled-unchecked"
        disabled
      >
        Disabled and Unchecked
      </RadioButton>
      
      <RadioButton
        name="disabledExample"
        value="disabled-checked"
        disabled
        checked={true}
      >
        Disabled and Checked
      </RadioButton>
    </div>
  );
}
```

### Settings Configuration

```tsx
import { Form, FormField, RadioButton, Button, Text } from '@delightui/components';

function SettingsConfigExample() {
  const handleSubmit = (data: any) => {
    console.log('Settings saved:', data);
  };

  return (
    <Form onSubmit={handleSubmit}>
      <FormField
        name="theme"
        label="Theme Preference"
      >
        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
          <RadioButton name="theme" value="light">
            Light Theme
          </RadioButton>
          <RadioButton name="theme" value="dark">
            Dark Theme
          </RadioButton>
          <RadioButton name="theme" value="auto">
            Auto (System Default)
          </RadioButton>
        </div>
      </FormField>

      <FormField
        name="language"
        label="Language"
      >
        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
          <RadioButton name="language" value="en">
            English
          </RadioButton>
          <RadioButton name="language" value="es">
            Spanish
          </RadioButton>
          <RadioButton name="language" value="fr">
            French
          </RadioButton>
          <RadioButton name="language" value="de">
            German
          </RadioButton>
        </div>
      </FormField>

      <FormField
        name="notifications"
        label="Notification Frequency"
      >
        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
          <RadioButton name="notifications" value="immediate">
            Immediate
          </RadioButton>
          <RadioButton name="notifications" value="daily">
            Daily Summary
          </RadioButton>
          <RadioButton name="notifications" value="weekly">
            Weekly Summary
          </RadioButton>
          <RadioButton name="notifications" value="never">
            Never
          </RadioButton>
        </div>
      </FormField>

      <Button type="submit">
        Save Settings
      </Button>
    </Form>
  );
}
```

### Quiz Application

```tsx
import { Form, FormField, RadioButton, Button, Text } from '@delightui/components';

function QuizExample() {
  const [currentQuestion, setCurrentQuestion] = useState(0);
  const [answers, setAnswers] = useState<Record<string, string>>({});

  const questions = [
    {
      id: 'q1',
      question: 'What is the capital of France?',
      options: [
        { value: 'london', label: 'London' },
        { value: 'berlin', label: 'Berlin' },
        { value: 'paris', label: 'Paris' },
        { value: 'madrid', label: 'Madrid' }
      ]
    },
    {
      id: 'q2',
      question: 'Which planet is closest to the Sun?',
      options: [
        { value: 'venus', label: 'Venus' },
        { value: 'mercury', label: 'Mercury' },
        { value: 'earth', label: 'Earth' },
        { value: 'mars', label: 'Mars' }
      ]
    }
  ];

  const handleNext = () => {
    if (currentQuestion < questions.length - 1) {
      setCurrentQuestion(currentQuestion + 1);
    }
  };

  const handleSubmit = () => {
    console.log('Quiz answers:', answers);
  };

  const question = questions[currentQuestion];

  return (
    <div style={{ maxWidth: '500px', margin: '0 auto' }}>
      <Text weight="bold" size="large" style={{ marginBottom: '16px' }}>
        Question {currentQuestion + 1} of {questions.length}
      </Text>
      
      <Text style={{ marginBottom: '20px' }}>
        {question.question}
      </Text>

      <div style={{ display: 'flex', flexDirection: 'column', gap: '12px', marginBottom: '24px' }}>
        {question.options.map((option) => (
          <RadioButton
            key={option.value}
            name={question.id}
            value={option.value}
            checked={answers[question.id] === option.value}
            onValueChange={(value) => setAnswers(prev => ({ ...prev, [question.id]: value as string }))}
          >
            {option.label}
          </RadioButton>
        ))}
      </div>

      <div style={{ display: 'flex', gap: '12px' }}>
        {currentQuestion < questions.length - 1 ? (
          <Button 
            onClick={handleNext}
            disabled={!answers[question.id]}
          >
            Next Question
          </Button>
        ) : (
          <Button 
            onClick={handleSubmit}
            disabled={!answers[question.id]}
          >
            Submit Quiz
          </Button>
        )}
      </div>
    </div>
  );
}
```

### Grouped Radio Buttons with Descriptions

```tsx
import { RadioButton, Text } from '@delightui/components';

function GroupedRadioWithDescriptionExample() {
  const [selectedPlan, setSelectedPlan] = useState('');

  const plans = [
    {
      value: 'basic',
      title: 'Basic Plan',
      description: 'Perfect for individuals getting started',
      price: '$9/month'
    },
    {
      value: 'pro',
      title: 'Pro Plan',
      description: 'Best for growing businesses',
      price: '$29/month'
    },
    {
      value: 'enterprise',
      title: 'Enterprise Plan',
      description: 'Advanced features for large organizations',
      price: '$99/month'
    }
  ];

  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
      {plans.map((plan) => (
        <div
          key={plan.value}
          style={{
            border: selectedPlan === plan.value ? '2px solid #007bff' : '1px solid #ccc',
            borderRadius: '8px',
            padding: '16px',
            cursor: 'pointer'
          }}
          onClick={() => setSelectedPlan(plan.value)}
        >
          <RadioButton
            name="subscriptionPlan"
            value={plan.value}
            checked={selectedPlan === plan.value}
            onValueChange={setSelectedPlan}
            labelAlignment="Right"
          >
            <div style={{ marginLeft: '8px' }}>
              <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center' }}>
                <Text weight="bold">{plan.title}</Text>
                <Text weight="bold" color="primary">{plan.price}</Text>
              </div>
              <Text size="small" color="secondary">
                {plan.description}
              </Text>
            </div>
          </RadioButton>
        </div>
      ))}
    </div>
  );
}
```

### Invalid State Example

```tsx
import { Form, FormField, RadioButton, Button, Text } from '@delightui/components';

function InvalidRadioButtonExample() {
  const [hasError, setHasError] = useState(false);
  const [selectedValue, setSelectedValue] = useState('');

  const handleSubmit = (data: any) => {
    if (!data.priority) {
      setHasError(true);
      return;
    }
    setHasError(false);
    console.log('Form submitted:', data);
  };

  return (
    <Form onSubmit={handleSubmit}>
      <FormField
        name="priority"
        label="Task Priority"
        required
        invalid={hasError}
        message={hasError ? "Please select a priority level" : undefined}
      >
        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
          <RadioButton
            name="priority"
            value="low"
            invalid={hasError}
            checked={selectedValue === 'low'}
            onValueChange={(value) => {
              setSelectedValue(value as string);
              if (hasError) setHasError(false);
            }}
          >
            Low Priority
          </RadioButton>
          <RadioButton
            name="priority"
            value="medium"
            invalid={hasError}
            checked={selectedValue === 'medium'}
            onValueChange={(value) => {
              setSelectedValue(value as string);
              if (hasError) setHasError(false);
            }}
          >
            Medium Priority
          </RadioButton>
          <RadioButton
            name="priority"
            value="high"
            invalid={hasError}
            checked={selectedValue === 'high'}
            onValueChange={(value) => {
              setSelectedValue(value as string);
              if (hasError) setHasError(false);
            }}
          >
            High Priority
          </RadioButton>
        </div>
      </FormField>

      <Button type="submit">
        Create Task
      </Button>
    </Form>
  );
}
```