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
Copy and paste the following code into your project.
/**
* 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
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.
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.
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.
radioClass
The classes for one native <input type="radio">. It takes no options; the input's own attributes carry the state.