# Radio Group

A set of checkable buttons, known as radio buttons, where no more than one of the buttons can be checked at a time.

Source: https://webjs.dev/ui/docs/components/radio-group

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { radioGroupClass, radioClass } from '#components/ui/radio-group.ts';
import { labelClass } from '#components/ui/label.ts';

export default function RadioGroupDemo() {
  return html`
    <div role="radiogroup" aria-label="Density" data-slot="radio-group" class=${cn(radioGroupClass(), 'w-fit')}>
      <div class="flex items-center gap-3">
        <input type="radio" data-slot="radio" name="radio-group-demo" value="default" id="r1" class=${radioClass()}>
        <label data-slot="label" for="r1" class=${labelClass()}>Default</label>
      </div>
      <div class="flex items-center gap-3">
        <input type="radio" data-slot="radio" name="radio-group-demo" value="comfortable" id="r2" checked class=${radioClass()}>
        <label data-slot="label" for="r2" class=${labelClass()}>Comfortable</label>
      </div>
      <div class="flex items-center gap-3">
        <input type="radio" data-slot="radio" name="radio-group-demo" value="compact" id="r3" class=${radioClass()}>
        <label data-slot="label" for="r3" class=${labelClass()}>Compact</label>
      </div>
    </div>
  `;
}
```

## Installation

```bash
npx @webjsdev/ui add radio-group
```

### Copy and paste the following code into your project.

````ts title="components/ui/radio-group.ts"
/**
 * RadioGroup: group of native radio inputs. Tier-1 class helpers;
 * compose with native `<input type="radio" name="...">` sharing a name.
 * The browser handles keyboard nav (Arrow keys), single-selection, and
 * form submission. No JS.
 *
 * shadcn parity:
 *   RadioGroup (orientation: horizontal | vertical)
 *                          → radioGroupClass({ orientation }) on a <div role="radiogroup">
 *   RadioGroupItem         → radioClass() on a native <input type="radio">
 *
 * Design tokens used: --input, --primary, --ring, --destructive.
 *
 * A11y (required for accessible output):
 *   The dot is drawn by the class itself, so a selected radio never differs
 *   from an unselected one by colour alone (WCAG 1.4.1), with or without
 *   JavaScript. Keep `data-slot="radio"` on the input, as every example here
 *   does, since the styles' field rules select on it.
 *   NAME THE GROUP. A bare `<div role="radiogroup">` has no accessible name, so
 *   a screen reader announces "radio group" with no idea what is being chosen.
 *   Point `aria-labelledby` at the visible group label, as below, or use a
 *   `<fieldset>` + `<legend>` instead of the `role="radiogroup"` div.
 *   Give every input the SAME `name`, which is what makes the browser treat
 *   them as one set: it supplies single-selection, Arrow-key navigation, and a
 *   single tab stop for free. Different names produce N independent radios that
 *   can all be selected at once.
 *   Label each input with `<label for>` pointing at its `id`, and mark the
 *   group `aria-invalid="true"` plus an `aria-describedby` error element when
 *   the selection fails validation.
 *
 * @example
 * ```html
 * <div class=${fieldClass()}>
 *   <span class=${fieldLabelClass()} id="plan-label">Billing plan</span>
 *   <div role="radiogroup" aria-labelledby="plan-label" class=${radioGroupClass()}>
 *     <div class="flex items-center gap-2">
 *       <input type="radio" data-slot="radio" name="plan" value="basic" id="plan-basic" class=${radioClass()}>
 *       <label class=${labelClass()} for="plan-basic">Basic</label>
 *     </div>
 *     <div class="flex items-center gap-2">
 *       <input type="radio" data-slot="radio" name="plan" value="pro" id="plan-pro" class=${radioClass()}>
 *       <label class=${labelClass()} for="plan-pro">Pro</label>
 *     </div>
 *   </div>
 * </div>
 * ```
 */
import { cn } from '../lib/utils.ts';

// The dot is a radial gradient in `currentColor`, the radio's own text colour,
// which the style chooses. shadcn's styles fill a checked radio with the
// primary colour and set `data-checked:text-primary-foreground`, so the dot is
// the light one on the fill; the default style keeps a transparent ring and
// sets `checked:text-primary`, so the dot is the primary one. A fixed colour
// (the SVG this replaced, one per theme) could only match one of the two, and
// disappeared into the fill under every shadcn style. Half the box across,
// as shadcn's indicator is. It rides the class itself, so a checked radio
// paints in the first paint and with JavaScript off.
const RADIO_CLASS =
  'size-4 appearance-none rounded-full border-input bg-transparent shadow-xs transition-[color,box-shadow] focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 checked:border-primary checked:text-primary checked:bg-no-repeat checked:bg-center dark:bg-input/30 dark:aria-invalid:ring-destructive/40 group/radio-group-item peer aspect-square shrink-0 border outline-none disabled:cursor-not-allowed disabled:opacity-50 checked:bg-[image:radial-gradient(circle_closest-side,currentColor_50%,transparent_calc(50%+0.5px))]';

/** Tailwind classes for a `<div role="radiogroup">` container. */
export type RadioGroupOrientation = 'vertical' | 'horizontal';

/**
 * Container for a group of native <input type="radio"> elements.
 *
 * Vertical (default): stacked column, gap-3. Matches Radix
 * RadioGroup.Root's default + the most common shadcn snippet.
 *
 * Horizontal: flex row that wraps. Picks `flex flex-wrap gap-x-6
 * gap-y-3` so multi-line wraps still have vertical breathing room.
 */
export function radioGroupClass(opts: { orientation?: RadioGroupOrientation } = {}): string {
  const orientation = opts.orientation ?? 'vertical';
  return orientation === 'horizontal'
    ? 'flex flex-wrap gap-x-6 gap-y-3'
    : 'grid gap-3';
}

/**
 * Tailwind classes for a styled `<input type="radio">`. The class draws the
 * checked dot itself, so a selected radio paints with JavaScript off. Keep
 * `data-slot="radio"` on the input as shadcn does.
 */
export function radioClass(): string {
  return cn(RADIO_CLASS);
}
````

### Update the import paths to match your project setup.

## Usage

```ts
import { labelClass } from '#components/ui/label.ts';
import { radioGroupClass, radioClass } from '#components/ui/radio-group.ts';
```

```ts
<div role="radiogroup" aria-label="Options" class=${radioGroupClass()}>
  <div class="flex items-center gap-3">
    <input type="radio" data-slot="radio" name="option" value="option-one" id="option-one" checked class=${radioClass()}>
    <label for="option-one" class=${labelClass()}>Option One</label>
  </div>
  <div class="flex items-center gap-3">
    <input type="radio" data-slot="radio" name="option" value="option-two" id="option-two" class=${radioClass()}>
    <label for="option-two" class=${labelClass()}>Option Two</label>
  </div>
</div>
```

## Composition

Use the following composition to build a radio group:

```text
radioGroupClass(), on a div with role="radiogroup"
├── radioClass(), on an input with type="radio"
└── radioClass(), on an input with type="radio"
```

The items are native radio inputs sharing one `name`, so the browser supplies single selection, arrow key navigation, a single tab stop and form submission, with no script. Keep `data-slot="radio"` on each input: it draws the dot of a checked radio.

## Description

Radio group items with a description using the [Field](https://webjs.dev/ui/docs/components/field) helpers.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  fieldClass, fieldContentClass, fieldLabelClass, fieldDescriptionClass,
} from '#components/ui/field.ts';
import { radioGroupClass, radioClass } from '#components/ui/radio-group.ts';

const options = [
  { value: 'default', id: 'desc-r1', label: 'Default', description: 'Standard spacing for most use cases.' },
  { value: 'comfortable', id: 'desc-r2', label: 'Comfortable', description: 'More space between elements.' },
  { value: 'compact', id: 'desc-r3', label: 'Compact', description: 'Minimal spacing for dense layouts.' },
];

export default function RadioGroupDescription() {
  const defaultValue = 'comfortable';

  return html`
    <div role="radiogroup" aria-label="Spacing" data-slot="radio-group" class=${cn(radioGroupClass(), 'w-fit')}>
      ${options.map((option) => html`
        <div role="group" data-slot="field" data-orientation="horizontal" class=${fieldClass({ orientation: 'horizontal' })}>
          <input type="radio" data-slot="radio" name="radio-group-description" value=${option.value} id=${option.id} ?checked=${option.value === defaultValue} class=${radioClass()}>
          <div data-slot="field-content" class=${fieldContentClass()}>
            <label data-slot="field-label" for=${option.id} class=${fieldLabelClass()}>${option.label}</label>
            <p data-slot="field-description" class=${fieldDescriptionClass()}>${option.description}</p>
          </div>
        </div>
      `)}
    </div>
  `;
}
```

## Choice Card

Use a `fieldLabelClass()` label to wrap the entire field for a clickable card-style selection.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  fieldClass, fieldContentClass, fieldLabelClass, fieldTitleClass, fieldDescriptionClass,
} from '#components/ui/field.ts';
import { radioGroupClass, radioClass } from '#components/ui/radio-group.ts';

const plans = [
  { value: 'plus', id: 'plus-plan', title: 'Plus', description: 'For individuals and small teams.' },
  { value: 'pro', id: 'pro-plan', title: 'Pro', description: 'For growing businesses.' },
  { value: 'enterprise', id: 'enterprise-plan', title: 'Enterprise', description: 'For large teams and enterprises.' },
];

// The whole card is the <label>, so a click anywhere on it picks the radio.
export default function RadioGroupChoiceCard() {
  const defaultValue = 'plus';

  return html`
    <div role="radiogroup" aria-label="Plan" data-slot="radio-group" class=${cn(radioGroupClass(), 'max-w-sm')}>
      ${plans.map((plan) => html`
        <label data-slot="field-label" for=${plan.id} class=${fieldLabelClass()}>
          <div role="group" data-slot="field" data-orientation="horizontal" class=${fieldClass({ orientation: 'horizontal' })}>
            <div data-slot="field-content" class=${fieldContentClass()}>
              <div data-slot="field-label" class=${fieldTitleClass()}>${plan.title}</div>
              <p data-slot="field-description" class=${fieldDescriptionClass()}>${plan.description}</p>
            </div>
            <input type="radio" data-slot="radio" name="radio-group-choice-card" value=${plan.value} id=${plan.id} ?checked=${plan.value === defaultValue} class=${radioClass()}>
          </div>
        </label>
      `)}
    </div>
  `;
}
```

## Fieldset

Use `fieldSetClass()` on a `<fieldset>` and `fieldLegendClass()` on its `<legend>` to group radio items with a label and description.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  fieldSetClass, fieldLegendClass, fieldClass, fieldLabelClass, fieldDescriptionClass,
} from '#components/ui/field.ts';
import { radioGroupClass, radioClass } from '#components/ui/radio-group.ts';

const plans = [
  { value: 'monthly', id: 'plan-monthly', label: 'Monthly ($9.99/month)' },
  { value: 'yearly', id: 'plan-yearly', label: 'Yearly ($99.99/year)' },
  { value: 'lifetime', id: 'plan-lifetime', label: 'Lifetime ($299.99)' },
];

export default function RadioGroupFieldset() {
  const defaultValue = 'monthly';

  return html`
    <fieldset data-slot="field-set" class=${cn(fieldSetClass(), 'w-full max-w-xs')}>
      <legend data-slot="field-legend" data-variant="label" class=${fieldLegendClass({ variant: 'label' })}>Subscription Plan</legend>
      <p data-slot="field-description" class=${fieldDescriptionClass()}>
        Yearly and lifetime plans offer significant savings.
      </p>
      <div role="radiogroup" data-slot="radio-group" class=${radioGroupClass()}>
        ${plans.map((plan) => html`
          <div role="group" data-slot="field" data-orientation="horizontal" class=${fieldClass({ orientation: 'horizontal' })}>
            <input type="radio" data-slot="radio" name="radio-group-fieldset" value=${plan.value} id=${plan.id} ?checked=${plan.value === defaultValue} class=${radioClass()}>
            <label data-slot="field-label" for=${plan.id} class=${cn(fieldLabelClass(), 'font-normal')}>
              ${plan.label}
            </label>
          </div>
        `)}
      </div>
    </fieldset>
  `;
}
```

## Disabled

Use the `disabled` attribute on a radio input to disable that item, and `data-disabled="true"` on its field to fade the label.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { fieldClass, fieldLabelClass } from '#components/ui/field.ts';
import { radioGroupClass, radioClass } from '#components/ui/radio-group.ts';

export default function RadioGroupDisabled() {
  return html`
    <div role="radiogroup" aria-label="Options" data-slot="radio-group" class=${cn(radioGroupClass(), 'w-fit')}>
      <div role="group" data-slot="field" data-orientation="horizontal" data-disabled="true" class=${fieldClass({ orientation: 'horizontal' })}>
        <input type="radio" data-slot="radio" name="radio-group-disabled" value="option1" id="disabled-1" disabled class=${radioClass()}>
        <label data-slot="field-label" for="disabled-1" class=${cn(fieldLabelClass(), 'font-normal')}>Disabled</label>
      </div>
      <div role="group" data-slot="field" data-orientation="horizontal" class=${fieldClass({ orientation: 'horizontal' })}>
        <input type="radio" data-slot="radio" name="radio-group-disabled" value="option2" id="disabled-2" checked class=${radioClass()}>
        <label data-slot="field-label" for="disabled-2" class=${cn(fieldLabelClass(), 'font-normal')}>Option 2</label>
      </div>
      <div role="group" data-slot="field" data-orientation="horizontal" class=${fieldClass({ orientation: 'horizontal' })}>
        <input type="radio" data-slot="radio" name="radio-group-disabled" value="option3" id="disabled-3" class=${radioClass()}>
        <label data-slot="field-label" for="disabled-3" class=${cn(fieldLabelClass(), 'font-normal')}>Option 3</label>
      </div>
    </div>
  `;
}
```

## Invalid

Use `aria-invalid` on the radio inputs and `data-invalid` on the field to show validation errors.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  fieldSetClass, fieldLegendClass, fieldClass, fieldLabelClass, fieldDescriptionClass,
} from '#components/ui/field.ts';
import { radioGroupClass, radioClass } from '#components/ui/radio-group.ts';

const options = [
  { value: 'email', id: 'invalid-email', label: 'Email only' },
  { value: 'sms', id: 'invalid-sms', label: 'SMS only' },
  { value: 'both', id: 'invalid-both', label: 'Both Email & SMS' },
];

export default function RadioGroupInvalid() {
  const defaultValue = 'email';

  return html`
    <fieldset data-slot="field-set" class=${cn(fieldSetClass(), 'w-full max-w-xs')}>
      <legend data-slot="field-legend" data-variant="label" class=${fieldLegendClass({ variant: 'label' })}>Notification Preferences</legend>
      <p data-slot="field-description" class=${fieldDescriptionClass()}>
        Choose how you want to receive notifications.
      </p>
      <div role="radiogroup" data-slot="radio-group" class=${radioGroupClass()}>
        ${options.map((option) => html`
          <div role="group" data-slot="field" data-orientation="horizontal" data-invalid="true" class=${fieldClass({ orientation: 'horizontal' })}>
            <input type="radio" data-slot="radio" name="radio-group-invalid" value=${option.value} id=${option.id} aria-invalid="true" ?checked=${option.value === defaultValue} class=${radioClass()}>
            <label data-slot="field-label" for=${option.id} class=${cn(fieldLabelClass(), 'font-normal')}>
              ${option.label}
            </label>
          </div>
        `)}
      </div>
    </fieldset>
  `;
}
```

## RTL

To enable RTL support, see the [RTL configuration guide](https://webjs.dev/ui/docs/rtl).

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  fieldClass, fieldContentClass, fieldLabelClass, fieldDescriptionClass,
} from '#components/ui/field.ts';
import { radioGroupClass, radioClass } from '#components/ui/radio-group.ts';

// shadcn's demo switches language with a selector; the page shows its
// default, Arabic.
const translations = {
  en: {
    dir: 'ltr',
    values: {
      default: 'Default',
      defaultDescription: 'Standard spacing for most use cases.',
      comfortable: 'Comfortable',
      comfortableDescription: 'More space between elements.',
      compact: 'Compact',
      compactDescription: 'Minimal spacing for dense layouts.',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      default: 'افتراضي',
      defaultDescription: 'تباعد قياسي لمعظم حالات الاستخدام.',
      comfortable: 'مريح',
      comfortableDescription: 'مساحة أكبر بين العناصر.',
      compact: 'مضغوط',
      compactDescription: 'تباعد أدنى للتخطيطات الكثيفة.',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      default: 'ברירת מחדל',
      defaultDescription: 'ריווח סטנדרטי לרוב מקרי השימוש.',
      comfortable: 'נוח',
      comfortableDescription: 'יותר מקום בין האלמנטים.',
      compact: 'קומפקטי',
      compactDescription: 'ריווח מינימלי לפריסות צפופות.',
    },
  },
};

export default function RadioGroupRtl() {
  const { dir, values: t } = translations.ar;
  const options = [
    { value: 'default', id: 'r1-rtl', label: t.default, description: t.defaultDescription },
    { value: 'comfortable', id: 'r2-rtl', label: t.comfortable, description: t.comfortableDescription },
    { value: 'compact', id: 'r3-rtl', label: t.compact, description: t.compactDescription },
  ];

  return html`
    <div role="radiogroup" aria-label="التباعد" dir=${dir} data-slot="radio-group" class=${cn(radioGroupClass(), 'w-fit')}>
      ${options.map((option) => html`
        <div role="group" data-slot="field" data-orientation="horizontal" class=${fieldClass({ orientation: 'horizontal' })}>
          <input type="radio" data-slot="radio" name="radio-group-rtl" value=${option.value} id=${option.id} ?checked=${option.value === 'comfortable'} class=${radioClass()}>
          <div data-slot="field-content" class=${fieldContentClass()}>
            <label data-slot="field-label" for=${option.id} class=${fieldLabelClass()}>${option.label}</label>
            <p data-slot="field-description" class=${fieldDescriptionClass()}>${option.description}</p>
          </div>
        </div>
      `)}
    </div>
  `;
}
```

## API Reference

The radio group is two class helpers over native radio inputs, so the state is the inputs' own: `checked` sets the default value, the shared `name` groups them, and a `change` event reports a new selection.

### radioGroupClass

The classes for the group container, a `<div role="radiogroup">`. Name the group with `aria-label` or `aria-labelledby`, or use a `<fieldset>` with a `<legend>` instead.

| Option | Type | Default |
| --- | --- | --- |
| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` |

### radioClass

The classes for one native `<input type="radio">`. It takes no options; the input's own attributes carry the state.

| Attribute | Type | Default |
| --- | --- | --- |
| `name` | `string` |  |
| `value` | `string` |  |
| `checked` | `boolean` | `false` |
| `disabled` | `boolean` | `false` |
| `required` | `boolean` | `false` |
| `data-slot` | `"radio"` | Required |
