Radio Group

A set of radio buttons where no more than one can be checked at a time.

import * as stylex from "@stylexjs/stylex"
import { Label } from "@/components/ui/label"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { HStack } from "@/components/ui/stack"

const styles = stylex.create({
  group: { width: "fit-content" },
})

export default function RadioGroupDemo() {
  return (
    <RadioGroup defaultValue="kelvin" xstyle={styles.group}>
      <HStack gap={3} align="center">
        <RadioGroupItem value="celsius" id="scale-celsius" />
        <Label htmlFor="scale-celsius">Celsius</Label>
      </HStack>
      <HStack gap={3} align="center">
        <RadioGroupItem value="kelvin" id="scale-kelvin" />
        <Label htmlFor="scale-kelvin">Kelvin</Label>
      </HStack>
      <HStack gap={3} align="center">
        <RadioGroupItem value="fahrenheit" id="scale-fahrenheit" />
        <Label htmlFor="scale-fahrenheit">Fahrenheit</Label>
      </HStack>
    </RadioGroup>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/radio-group

Needs the arene setup first.

Usage

import { Label } from "@/components/ui/label"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
<RadioGroup defaultValue="kelvin">
  <HStack gap={3} align="center">
    <RadioGroupItem value="kelvin" id="r1" />
    <Label htmlFor="r1">Kelvin</Label>
  </HStack>
</RadioGroup>

RadioGroup is a grid that fills its container and stacks its children. Match each label's htmlFor to its button's id, or wrap the button in the label.

RadioGroup
├── RadioGroupItem
└── RadioGroupItem

Selected value

Use defaultValue for an uncontrolled group, or value and onValueChange to control it. value is the value of the selected RadioGroupItem, which can be any type.

const [scale, setScale] = useState("kelvin")

return (
  <RadioGroup value={scale} onValueChange={setScale}>
    …
  </RadioGroup>
)

Description

Put a Field around each button and a FieldContent beside it to add a line of helper text under the label.

Water freezes at 0 and boils at 100.

Starts at absolute zero, so never negative.

Water freezes at 32 and boils at 212.

import * as stylex from "@stylexjs/stylex"
import { Field, FieldContent, FieldDescription, FieldLabel } from "@/components/ui/field"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { width } from "@/theme/tokens.stylex"

const styles = stylex.create({
  group: { maxWidth: width.sm },
})

const scales = [
  { id: "celsius", title: "Celsius", description: "Water freezes at 0 and boils at 100." },
  { id: "kelvin", title: "Kelvin", description: "Starts at absolute zero, so never negative." },
  { id: "fahrenheit", title: "Fahrenheit", description: "Water freezes at 32 and boils at 212." },
]

export default function RadioGroupDescription() {
  return (
    <RadioGroup defaultValue="kelvin" xstyle={styles.group}>
      {scales.map((scale) => (
        <Field key={scale.id} orientation="horizontal">
          <RadioGroupItem value={scale.id} id={`desc-${scale.id}`} />
          <FieldContent>
            <FieldLabel>{scale.title}</FieldLabel>
            <FieldDescription>{scale.description}</FieldDescription>
          </FieldContent>
        </Field>
      ))}
    </RadioGroup>
  )
}

Choice card

Wrap a whole Field in a FieldLabel to turn the option into a card, and pass checked to mark the selected one.

"use client"

import { useState } from "react"
import * as stylex from "@stylexjs/stylex"
import { Field, FieldContent, FieldDescription, FieldLabel, FieldTitle } from "@/components/ui/field"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { width } from "@/theme/tokens.stylex"

const styles = stylex.create({
  group: { maxWidth: width.sm },
})

const plans = [
  { id: "student", title: "Student", description: "For one person and one notebook." },
  { id: "lab", title: "Lab", description: "For a research group of up to ten." },
  { id: "institute", title: "Institute", description: "For departments with many groups." },
]

export default function RadioGroupChoiceCard() {
  const [plan, setPlan] = useState("student")

  return (
    <RadioGroup value={plan} onValueChange={setPlan} xstyle={styles.group}>
      {plans.map((entry) => (
        <FieldLabel key={entry.id} htmlFor={`plan-${entry.id}`} checked={plan === entry.id}>
          <Field orientation="horizontal">
            <FieldContent>
              <FieldTitle>{entry.title}</FieldTitle>
              <FieldDescription>{entry.description}</FieldDescription>
            </FieldContent>
            <RadioGroupItem value={entry.id} id={`plan-${entry.id}`} />
          </Field>
        </FieldLabel>
      ))}
    </RadioGroup>
  )
}

FieldLabel cannot read the button's state, so checked is a prop you set from the same value you give RadioGroup. That makes the card a controlled group.

Fieldset

Use Fieldset and FieldsetLegend to caption the group as a whole, and give the group a name to submit it with a form.

Billing period

Paying yearly costs two months less than monthly.

import * as stylex from "@stylexjs/stylex"
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
import { FieldsetLegend, Fieldset } from "@/components/ui/fieldset"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { textStyles } from "@/components/ui/text"
import { width } from "@/theme/tokens.stylex"

const styles = stylex.create({
  fieldset: { maxWidth: width.xs },
})

const plans = [
  { id: "monthly", label: "Monthly ($12/month)" },
  { id: "yearly", label: "Yearly ($120/year)" },
  { id: "lifetime", label: "Lifetime ($360)" },
]

export default function RadioGroupFieldset() {
  return (
    <Fieldset xstyle={styles.fieldset}>
      <FieldsetLegend variant="label">Billing period</FieldsetLegend>
      <FieldDescription>Paying yearly costs two months less than monthly.</FieldDescription>
      <RadioGroup defaultValue="monthly" name="subscription-plan">
        {plans.map((plan) => (
          <Field key={plan.id} orientation="horizontal">
            <RadioGroupItem value={plan.id} id={`billing-${plan.id}`} />
            <FieldLabel xstyle={textStyles.weights.normal}>{plan.label}</FieldLabel>
          </Field>
        ))}
      </RadioGroup>
    </Fieldset>
  )
}

Disabled

Set disabled on Field to disable its control and dim its label, or on a bare control directly.

import * as stylex from "@stylexjs/stylex"
import { Field, FieldLabel } from "@/components/ui/field"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { textStyles } from "@/components/ui/text"

const styles = stylex.create({
  group: { width: "fit-content" },
})

export default function RadioGroupDisabled() {
  return (
    <RadioGroup defaultValue="standard" xstyle={styles.group}>
      <Field orientation="horizontal" disabled>
        <RadioGroupItem value="free" id="shipping-free" />
        <FieldLabel xstyle={textStyles.weights.normal}>Free (unavailable)</FieldLabel>
      </Field>
      <Field orientation="horizontal">
        <RadioGroupItem value="standard" id="shipping-standard" />
        <FieldLabel xstyle={textStyles.weights.normal}>Standard</FieldLabel>
      </Field>
      <Field orientation="horizontal">
        <RadioGroupItem value="express" id="shipping-express" />
        <FieldLabel xstyle={textStyles.weights.normal}>Express</FieldLabel>
      </Field>
    </RadioGroup>
  )
}

Invalid

Set invalid on Field to style its control, or aria-invalid on a bare control. The examples show both.

import { Field, FieldLabel, FieldError } from "@/components/ui/field"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { Label } from "@/components/ui/label"
import { HStack, VStack } from "@/components/ui/stack"
const channels = [
  { id: "email", label: "Email" },
  { id: "sms", label: "Text message" },
  { id: "both", label: "Email and text" },
]
function Options({ bare = false }: { bare?: boolean }) {
  return (
    <RadioGroup aria-label={bare ? "Run alerts" : undefined}>
      {channels.map((channel) => (
        <HStack key={channel.id} gap={2} align="center">
          <RadioGroupItem
            value={channel.id}
            id={`${bare ? "bare" : "field"}-notify-${channel.id}`}
            aria-invalid={bare || undefined}
          />
          <Label htmlFor={`${bare ? "bare" : "field"}-notify-${channel.id}`}>{channel.label}</Label>
        </HStack>
      ))}
    </RadioGroup>
  )
}
export default function RadioGroupInvalid() {
  return (
    <VStack gap={5}>
      <Options bare />
      <Field invalid>
        <FieldLabel>Run alerts</FieldLabel>
        <Options />
        <FieldError>Choose where run alerts should go.</FieldError>
      </Field>
    </VStack>
  )
}

API reference

Pass render to replace a part's element or compose it with another component.

Both parts wrap the Base UI RadioGroup and Radio primitives and accept their props. See the Base UI reference. Each part also takes xstyle and className.

RadioGroup

PropTypeDefault
valueValue—
defaultValueValue—
onValueChange(value: Value, details) => void—
namestring—
disabledbooleanfalse
readOnlybooleanfalse
requiredbooleanfalse
formstring—
xstyleStyleXStyles—
classNamestring—

The root is a <div role="radiogroup">. Arrow keys move between the buttons and select as they go, and the group is one tab stop.

RadioGroupItem

PropTypeDefault
valueValue—
disabledbooleanfalse
readOnlybooleanfalse
requiredbooleanfalse
aria-invalidboolean—
idstring—
inputRefRef<HTMLInputElement>—
xstyleStyleXStyles—
styleCSSProperties—
classNamestring—

The item is a <span role="radio">. Base UI renders a hidden <input> beside it that carries id, name and value. A label's htmlFor and a form submission reach the item through that input.

radioGroupStyles

The style maps behind the component. Spread them onto any element.

KeyWhat it is
groupThe grid and its gap
itemThe circle: size, border width, hit area
indicatorThe dot and its fade
indicatorHiddenThe dot faded out and scaled down
choiceThe hairline edge and fill at a choice's size
checkedThe flat primary fill and inverted dot colour
disabledThe dimmed, non-interactive state
invalidThe destructive border and ring

item has no colour and no focus ring. Everything else comes from states in theme/states.ts, the same material the checkbox uses. Merge choice, then states.focusRing. Merge invalid before checked, so a selected invalid button keeps the primary fill and shows only the destructive ring.

Data attributes

AttributeOnEffect
data-slot="radio-group"the rootTargets the grid from a parent
data-slot="radio-group-item"a buttonTargets the circle
data-slot="radio-group-indicator"the dotTargets the animated indicator
data-checked, data-uncheckeditem, dotBase UI writes them
data-disabled, data-readonly, data-requiredroot, itemBase UI writes them
data-starting-style, data-ending-stylethe dotBase UI writes them while the dot enters or leaves