Skip to content
WebJs
Menu

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.

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>
  `;
}
View Code

Installation

pnpm dlx @webjsdev/ui add radio-group

Usage

import { labelClass } from '#components/ui/label.ts';
import { radioGroupClass, radioClass } from '#components/ui/radio-group.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:

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 helpers.

Standard spacing for most use cases.

More space between elements.

Minimal spacing for dense layouts.

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>
  `;
}
View Code

Choice Card

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

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>
  `;
}
View Code

Fieldset

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

Subscription Plan

Yearly and lifetime plans offer significant savings.

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>
  `;
}
View Code

Disabled

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

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>
  `;
}
View Code

Invalid

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

Notification Preferences

Choose how you want to receive notifications.

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>
  `;
}
View Code

RTL

To enable RTL support, see the RTL configuration guide.

تباعد قياسي لمعظم حالات الاستخدام.

مساحة أكبر بين العناصر.

تباعد أدنى للتخطيطات الكثيفة.

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>
  `;
}
View Code

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.

OptionTypeDefault
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.

AttributeTypeDefault
namestring
valuestring
checkedbooleanfalse
disabledbooleanfalse
requiredbooleanfalse
data-slot"radio"Required