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.

RadioGroup wraps Kobalte's Radio Group primitive, which implements the WAI-ARIA radio group pattern with roving-tabindex keyboard navigation and native form participation.

Default

Comfortable

Compact

1
import { Label } from "~/components/ui/label";
2
import { RadioGroup, RadioGroupItem } from "~/components/ui/radio-group";
3

4
export default function RadioGroupDemo() {
5
  return (
6
    <RadioGroup defaultValue="comfortable" class="w-fit">
7
      <div class="flex items-center gap-3">
8
        <RadioGroupItem value="default" id="radio-group-demo-default" />
9
        <Label for="radio-group-demo-default">Default</Label>
10
      </div>
11
      <div class="flex items-center gap-3">
12
        <RadioGroupItem value="comfortable" id="radio-group-demo-comfortable" />
13
        <Label for="radio-group-demo-comfortable">Comfortable</Label>
14
      </div>
15
      <div class="flex items-center gap-3">
16
        <RadioGroupItem value="compact" id="radio-group-demo-compact" />
17
        <Label for="radio-group-demo-compact">Compact</Label>
18
      </div>
19
    </RadioGroup>
20
  );
21
}

Installation

pnpm dlx shadcn@latest add @zaidan/radio-group
npx shadcn@latest add @zaidan/radio-group
yarn dlx shadcn@latest add @zaidan/radio-group
bunx --bun shadcn@latest add @zaidan/radio-group

Usage

1
import { Label } from "~/components/ui/label";
2
import { RadioGroup, RadioGroupItem } from "~/components/ui/radio-group";

1
<RadioGroup defaultValue="option-one">
2
  <div class="flex items-center gap-3">
3
    <RadioGroupItem value="option-one" id="option-one" />
4
    <Label for="option-one">Option One</Label>
5
  </div>
6
  <div class="flex items-center gap-3">
7
    <RadioGroupItem value="option-two" id="option-two" />
8
    <Label for="option-two">Option Two</Label>
9
  </div>
10
</RadioGroup>

Composition

Use the following composition to build a RadioGroup:

RadioGroup
├── RadioGroupItem
└── RadioGroupItem

Description

Radio group items with a description using the Field component.

Default

Standard spacing for most use cases.

Comfortable

More space between elements.

Compact

Minimal spacing for dense layouts.

1
import { Field, FieldContent, FieldDescription, FieldLabel } from "~/components/ui/field";
2
import { RadioGroup, RadioGroupItem } from "~/components/ui/radio-group";
3

4
export default function RadioGroupDescription() {
5
  return (
6
    <RadioGroup defaultValue="comfortable" class="w-fit">
7
      <Field orientation="horizontal">
8
        <RadioGroupItem value="default" id="radio-group-description-default" />
9
        <FieldContent>
10
          <FieldLabel for="radio-group-description-default">Default</FieldLabel>
11
          <FieldDescription>Standard spacing for most use cases.</FieldDescription>
12
        </FieldContent>
13
      </Field>
14
      <Field orientation="horizontal">
15
        <RadioGroupItem value="comfortable" id="radio-group-description-comfortable" />
16
        <FieldContent>
17
          <FieldLabel for="radio-group-description-comfortable">Comfortable</FieldLabel>
18
          <FieldDescription>More space between elements.</FieldDescription>
19
        </FieldContent>
20
      </Field>
21
      <Field orientation="horizontal">
22
        <RadioGroupItem value="compact" id="radio-group-description-compact" />
23
        <FieldContent>
24
          <FieldLabel for="radio-group-description-compact">Compact</FieldLabel>
25
          <FieldDescription>Minimal spacing for dense layouts.</FieldDescription>
26
        </FieldContent>
27
      </Field>
28
    </RadioGroup>
29
  );
30
}

Choice Card

Use FieldLabel to wrap the entire Field for a clickable card-style selection.

Plus

For individuals and small teams.

Pro

For growing businesses.

Enterprise

For large teams and enterprises.

1
import {
2
  Field,
3
  FieldContent,
4
  FieldDescription,
5
  FieldLabel,
6
  FieldTitle,
7
} from "~/components/ui/field";
8
import { RadioGroup, RadioGroupItem } from "~/components/ui/radio-group";
9

10
export default function RadioGroupChoiceCard() {
11
  return (
12
    <RadioGroup defaultValue="plus" class="max-w-sm">
13
      <FieldLabel for="radio-group-plan-plus">
14
        <Field orientation="horizontal">
15
          <FieldContent>
16
            <FieldTitle>Plus</FieldTitle>
17
            <FieldDescription>For individuals and small teams.</FieldDescription>
18
          </FieldContent>
19
          <RadioGroupItem value="plus" id="radio-group-plan-plus" />
20
        </Field>
21
      </FieldLabel>
22
      <FieldLabel for="radio-group-plan-pro">
23
        <Field orientation="horizontal">
24
          <FieldContent>
25
            <FieldTitle>Pro</FieldTitle>
26
            <FieldDescription>For growing businesses.</FieldDescription>
27
          </FieldContent>
28
          <RadioGroupItem value="pro" id="radio-group-plan-pro" />
29
        </Field>
30
      </FieldLabel>
31
      <FieldLabel for="radio-group-plan-enterprise">
32
        <Field orientation="horizontal">
33
          <FieldContent>
34
            <FieldTitle>Enterprise</FieldTitle>
35
            <FieldDescription>For large teams and enterprises.</FieldDescription>
36
          </FieldContent>
37
          <RadioGroupItem value="enterprise" id="radio-group-plan-enterprise" />
38
        </Field>
39
      </FieldLabel>
40
    </RadioGroup>
41
  );
42
}

Fieldset

Use FieldSet and FieldLegend to group radio items with a label and description.

Subscription Plan

Yearly and lifetime plans offer significant savings.

Monthly ($9.99/month)

Yearly ($99.99/year)

Lifetime ($299.99)

1
import {
2
  Field,
3
  FieldDescription,
4
  FieldLabel,
5
  FieldLegend,
6
  FieldSet,
7
} from "~/components/ui/field";
8
import { RadioGroup, RadioGroupItem } from "~/components/ui/radio-group";
9

10
export default function RadioGroupFieldset() {
11
  return (
12
    <FieldSet class="w-full max-w-xs">
13
      <FieldLegend variant="label">Subscription Plan</FieldLegend>
14
      <FieldDescription>Yearly and lifetime plans offer significant savings.</FieldDescription>
15
      <RadioGroup defaultValue="monthly">
16
        <Field orientation="horizontal">
17
          <RadioGroupItem value="monthly" id="radio-group-plan-monthly" />
18
          <FieldLabel for="radio-group-plan-monthly" class="font-normal">
19
            Monthly ($9.99/month)
20
          </FieldLabel>
21
        </Field>
22
        <Field orientation="horizontal">
23
          <RadioGroupItem value="yearly" id="radio-group-plan-yearly" />
24
          <FieldLabel for="radio-group-plan-yearly" class="font-normal">
25
            Yearly ($99.99/year)
26
          </FieldLabel>
27
        </Field>
28
        <Field orientation="horizontal">
29
          <RadioGroupItem value="lifetime" id="radio-group-plan-lifetime" />
30
          <FieldLabel for="radio-group-plan-lifetime" class="font-normal">
31
            Lifetime ($299.99)
32
          </FieldLabel>
33
        </Field>
34
      </RadioGroup>
35
    </FieldSet>
36
  );
37
}

Disabled

Use the disabled prop on RadioGroup to disable all items, or on RadioGroupItem to disable an individual item.

Disabled

Option 2

Option 3

1
import { Field, FieldLabel } from "~/components/ui/field";
2
import { RadioGroup, RadioGroupItem } from "~/components/ui/radio-group";
3

4
export default function RadioGroupDisabled() {
5
  return (
6
    <RadioGroup defaultValue="option2" class="w-fit">
7
      <Field orientation="horizontal" data-disabled>
8
        <RadioGroupItem value="option1" id="radio-group-disabled-1" disabled />
9
        <FieldLabel for="radio-group-disabled-1" class="font-normal">
10
          Disabled
11
        </FieldLabel>
12
      </Field>
13
      <Field orientation="horizontal">
14
        <RadioGroupItem value="option2" id="radio-group-disabled-2" />
15
        <FieldLabel for="radio-group-disabled-2" class="font-normal">
16
          Option 2
17
        </FieldLabel>
18
      </Field>
19
      <Field orientation="horizontal">
20
        <RadioGroupItem value="option3" id="radio-group-disabled-3" />
21
        <FieldLabel for="radio-group-disabled-3" class="font-normal">
22
          Option 3
23
        </FieldLabel>
24
      </Field>
25
    </RadioGroup>
26
  );
27
}

Invalid

Use aria-invalid on RadioGroupItem and data-invalid on Field to show validation errors.

Notification Preferences

Choose how you want to receive notifications.

Email only

SMS only

Both Email & SMS

1
import {
2
  Field,
3
  FieldDescription,
4
  FieldLabel,
5
  FieldLegend,
6
  FieldSet,
7
} from "~/components/ui/field";
8
import { RadioGroup, RadioGroupItem } from "~/components/ui/radio-group";
9

10
export default function RadioGroupInvalid() {
11
  return (
12
    <FieldSet class="w-full max-w-xs">
13
      <FieldLegend variant="label">Notification Preferences</FieldLegend>
14
      <FieldDescription>Choose how you want to receive notifications.</FieldDescription>
15
      <RadioGroup defaultValue="email">
16
        <Field orientation="horizontal" data-invalid>
17
          <RadioGroupItem value="email" id="radio-group-invalid-email" aria-invalid />
18
          <FieldLabel for="radio-group-invalid-email" class="font-normal">
19
            Email only
20
          </FieldLabel>
21
        </Field>
22
        <Field orientation="horizontal" data-invalid>
23
          <RadioGroupItem value="sms" id="radio-group-invalid-sms" aria-invalid />
24
          <FieldLabel for="radio-group-invalid-sms" class="font-normal">
25
            SMS only
26
          </FieldLabel>
27
        </Field>
28
        <Field orientation="horizontal" data-invalid>
29
          <RadioGroupItem value="both" id="radio-group-invalid-both" aria-invalid />
30
          <FieldLabel for="radio-group-invalid-both" class="font-normal">
31
            Both Email & SMS
32
          </FieldLabel>
33
        </Field>
34
      </RadioGroup>
35
    </FieldSet>
36
  );
37
}

RadioGroup and RadioGroupItem wrap Kobalte's Radio Group primitive, which implements the WAI-ARIA radio group pattern, including roving-tabindex keyboard navigation, disabled, read-only, and form reset behavior.

RadioGroup

Prop	Type	Default
`value`	`string`	-
`defaultValue`	`string`	-
`onChange`	`(value: string) => void`	-
`orientation`	`"horizontal" \| "vertical"`	`"vertical"`
`disabled`	`boolean`	`false`
`readOnly`	`boolean`	`false`
`required`	`boolean`	`false`
`validationState`	`"valid" \| "invalid"`	-
`name`	`string`	-
`id`	`string`	-
`as`	`ValidComponent`	`"div"`
`class`	`string`	-

RadioGroupItem

Prop	Type	Default
`value`	`string`	-
`disabled`	`boolean`	`false`
`id`	`string`	-
`as`	`ValidComponent`	`"div"`
`class`	`string`	-