Forms

Radio Group

A set of mutually exclusive radio buttons where only one can be selected at a time.

Preview

'use client';

import { Label } from '@brika/clay/components/label';
import { RadioGroup, RadioGroupItem } from '@brika/clay/components/radio-group';

/** Vertical radio group with a default value pre-selected. */
export default function RadioGroupDefaultDemo() {
  return (
    <RadioGroup defaultValue="comfortable">
      <div className="flex items-center gap-2">
        <RadioGroupItem value="default" id="r1" />
        <Label htmlFor="r1">Default</Label>
      </div>
      <div className="flex items-center gap-2">
        <RadioGroupItem value="comfortable" id="r2" />
        <Label htmlFor="r2">Comfortable</Label>
      </div>
      <div className="flex items-center gap-2">
        <RadioGroupItem value="compact" id="r3" />
        <Label htmlFor="r3">Compact</Label>
      </div>
    </RadioGroup>
  );
}

01 Installation

Install

Pull Radio Group from the barrel for everyday use, or the granular path when you want a tighter bundle.

tsxBarrel1 line

import { RadioGroup } from "@brika/clay";

tsxGranular1 line

import { RadioGroup } from "@brika/clay/components/radio-group";

02 Usage

A minimal example

Drop this into a page. Native HTML attributes pass through to the underlying primitive.

tsxRadio Group.tsx24 lines

'use client';

import { Label } from '@brika/clay/components/label';
import { RadioGroup, RadioGroupItem } from '@brika/clay/components/radio-group';

/** Vertical radio group with a default value pre-selected. */
export default function RadioGroupDefaultDemo() {
  return (
    <RadioGroup defaultValue="comfortable">
      <div className="flex items-center gap-2">
        <RadioGroupItem value="default" id="r1" />
        <Label htmlFor="r1">Default</Label>
      </div>
      <div className="flex items-center gap-2">
        <RadioGroupItem value="comfortable" id="r2" />
        <Label htmlFor="r2">Comfortable</Label>
      </div>
      <div className="flex items-center gap-2">
        <RadioGroupItem value="compact" id="r3" />
        <Label htmlFor="r3">Compact</Label>
      </div>
    </RadioGroup>
  );
}

03 Examples

Radio Group, every way

Controlled

Fully controlled radio group that shows the selected value.

GitHub

'use client';

import { Label } from '@brika/clay/components/label';
import { RadioGroup, RadioGroupItem } from '@brika/clay/components/radio-group';
import { useState } from 'react';

/** Fully controlled radio group that shows the selected value. */
export default function RadioGroupControlledDemo() {
  const [value, setValue] = useState('medium');

  return (
    <div className="space-y-3">
      <RadioGroup value={value} onValueChange={setValue}>
        <div className="flex items-center gap-2">
          <RadioGroupItem value="low" id="priority-low" />
          <Label htmlFor="priority-low">Low priority</Label>
        </div>
        <div className="flex items-center gap-2">
          <RadioGroupItem value="medium" id="priority-medium" />
          <Label htmlFor="priority-medium">Medium priority</Label>
        </div>
        <div className="flex items-center gap-2">
          <RadioGroupItem value="high" id="priority-high" />
          <Label htmlFor="priority-high">High priority</Label>
        </div>
      </RadioGroup>
      <p className="font-mono text-clay-subtle text-xs">selected: {value}</p>
    </div>
  );
}

Disabled

One item disabled independently while others remain interactive.

GitHub

'use client';

import { Label } from '@brika/clay/components/label';
import { RadioGroup, RadioGroupItem } from '@brika/clay/components/radio-group';

/** One item disabled independently while others remain interactive. */
export default function RadioGroupDisabledDemo() {
  return (
    <RadioGroup defaultValue="monthly">
      <div className="flex items-center gap-2">
        <RadioGroupItem value="monthly" id="plan-monthly" />
        <Label htmlFor="plan-monthly">Monthly billing</Label>
      </div>
      <div className="flex items-center gap-2">
        <RadioGroupItem value="annual" id="plan-annual" />
        <Label htmlFor="plan-annual">Annual billing</Label>
      </div>
      <div className="flex items-center gap-2">
        <RadioGroupItem value="enterprise" id="plan-enterprise" disabled />
        <Label htmlFor="plan-enterprise" className="opacity-50">Enterprise (contact sales)</Label>
      </div>
    </RadioGroup>
  );
}

Horizontal

Horizontal layout using orientation="horizontal" and flex-row spacing.

GitHub

'use client';

import { Label } from '@brika/clay/components/label';
import { RadioGroup, RadioGroupItem } from '@brika/clay/components/radio-group';

/** Horizontal layout using orientation="horizontal" and flex-row spacing. */
export default function RadioGroupHorizontalDemo() {
  return (
    <RadioGroup defaultValue="card" orientation="horizontal" className="flex flex-row gap-6">
      <div className="flex items-center gap-2">
        <RadioGroupItem value="card" id="pay-card" />
        <Label htmlFor="pay-card">Credit card</Label>
      </div>
      <div className="flex items-center gap-2">
        <RadioGroupItem value="bank" id="pay-bank" />
        <Label htmlFor="pay-bank">Bank transfer</Label>
      </div>
      <div className="flex items-center gap-2">
        <RadioGroupItem value="crypto" id="pay-crypto" />
        <Label htmlFor="pay-crypto">Crypto</Label>
      </div>
    </RadioGroup>
  );
}

04 Accessibility

Accessibility

Arrow keys move selection within the group, Tab leaves the group entirely.
Always pair items with visible <Label htmlFor={id}> elements.
Disabled individual items carry aria-disabled and are skipped by arrow keys.
Use defaultValue for uncontrolled initial selection; value + onValueChange for controlled.

05 Tokens 13 theme-overridable

Theme tokens

Every CSS variable Radio Group reads, with its default and the dotted path you'd write in a ThemeConfig JSON to override it. Set any of these in your theme to retune Radio Group without touching component code.

Radio Group tokens

13 tokens

ColorFill, border, and text colors.7

--radio-group-unchecked-containercolorvar(--input-container)
components.radioGroup.uncheckedContainer
Disc background in the resting (unchecked) state.
--radio-group-unchecked-bordercolorvar(--input-border)
components.radioGroup.uncheckedBorder
Disc border color in the resting (unchecked) state.
--radio-group-checked-containercolorvar(--primary)
components.radioGroup.checkedContainer
Disc background when selected (`data-[state=checked]`).
--radio-group-checked-bordercolorvar(--primary)
components.radioGroup.checkedBorder
Disc border color when selected.
--radio-group-indicator-colorcolorvar(--primary-foreground)
components.radioGroup.indicatorColor
Color of the inner dot painted on the selected disc.
--radio-group-invalid-bordercolorvar(--destructive)
components.radioGroup.invalidBorder
Disc border color when the radio has `aria-invalid="true"`. Defaults to the theme destructive hue.
--radio-group-invalid-ringcolorvar(--destructive)
components.radioGroup.invalidRing
Color of the invalid-state focus halo. Painted at 20% opacity in light mode, 40% in dark mode for parity with other form controls.

GeometrySizes, lengths, and corner radii.2

--radio-group-sizesize1rem
components.radioGroup.size
Radio button diameter.
--radio-group-radiusradius9999px
components.radioGroup.radius
Radio button border radius.

BorderBorder width and style.2

--radio-group-border-widthborder-width1px
components.radioGroup.borderWidth
Border width on the radio-group. Set non-zero for outline-style variants.
--radio-group-border-styleborder-stylesolid
components.radioGroup.borderStyle
Border style on the radio-group (`solid`, `dashed`, `double`, `none`).

MotionAnimation duration and easing.2

--radio-group-durationdurationvar(--motion-standard-duration)
components.radioGroup.duration
Transition duration for radio-group state changes.
--radio-group-easingeasingvar(--motion-standard-easing)
components.radioGroup.easing
Transition easing for radio-group state changes.

Override in a theme

Authoring a theme is plain JSON. Drop overrides under components.radioGroup, the names are camelCase versions of the variable suffix.

jsonmy-theme.json12 lines

{
  "id": "my-theme",
  "name": "My Theme",
  "description": "...",
  "accentSwatches": ["#000"],

  "components": {
    "radioGroup": {
      "radius": "9999px"
    }
  }
}

Then apply with applyTheme(myTheme) (see the theming guide), scope it to a subtree with themeToCssVars(myTheme, mode), or consume any token directly in your own JSX with the matching Tailwind utility (e.g. bg-radio-group-…) — see the chips on each token row.

06 API reference

API reference

Props specific to Radio Group. Native HTML attributes pass through to the underlying primitive, see the component source on GitHub for the full type signature.

<RadioGroup />

passthrough

No wrapper-specific props, all attributes pass through to the underlying primitive.

<RadioGroupItem />

passthrough

No wrapper-specific props, all attributes pass through to the underlying primitive.