Single-choice radios with optional full-card labels, descriptions, and large pointer targets around Radix keyboard navigation.
What changed
- 1.0.1 Oct 11, 2026Switch track, thumb travel, and checkbox and radio size follow the platform feel tokens (--bm-switch-*, --bm-check-size); select and command surfaces take the feel's frosting. Unchanged without a feel.
- 1.0.0 Sep 30, 2026First release.
Digest frequency
Choose when to get your project summary.
"use client";
import * as React from "react";
import { RadioGroup, RadioGroupOption } from "@/components/ballmac/radio-group";
export default function RadioGroupDemo() {
const [value, setValue] = React.useState("weekly");
return (
<div className="w-full max-w-sm">
<p className="mb-1 text-sm font-semibold">Digest frequency</p>
<p className="mb-4 text-sm text-muted-foreground">
Choose when to get your project summary.
</p>
<RadioGroup
aria-label="Digest frequency"
value={value}
onValueChange={setValue}
>
<RadioGroupOption
value="daily"
title="Daily"
description="A brief update every morning"
/>
<RadioGroupOption
value="weekly"
title="Weekly"
description="A focused summary each Monday"
/>
<RadioGroupOption
value="off"
title="Off"
description="Only important account notices"
/>
</RadioGroup>
</div>
);
}Installation
The default, and what a Radix-style project installs.
$ pnpm dlx shadcn@latest add @ballmac/radio-groupInstall the dependencies.
$ pnpm add radix-ui lucide-reactAdd the Ballmac items it builds on.
$ pnpm dlx shadcn@latest add @ballmac/directionCopy the source into your project.
components/ballmac/radio-group.tsx// Ballmac UI: Radio Group. https://ui.ballmac.com/components/radio-group "use client"; import * as React from "react"; import { Circle } from "lucide-react"; import { RadioGroup as Primitive } from "radix-ui"; import { useDirection } from "@/lib/ballmac/direction"; import { cn } from "@/lib/utils"; type RadioGroupProps = React.ComponentProps<typeof Primitive.Root>; function RadioGroup({ className, ...props }: RadioGroupProps) { const dir = useDirection(props.dir); return ( <Primitive.Root dir={dir} data-slot="radio-group" className={cn("grid gap-2", className)} {...props} /> ); } type RadioGroupItemProps = React.ComponentProps<typeof Primitive.Item>; function RadioGroupItem({ className, ...props }: RadioGroupItemProps) { return ( <Primitive.Item data-slot="radio-group-item" className={cn( "aspect-square size-[var(--bm-check-size,calc(var(--spacing)*4))] shrink-0 rounded-full border border-input bg-background text-primary shadow-xs outline-none transition-[color,border-color,box-shadow] duration-150 focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:border-primary motion-reduce:transition-none", className, )} {...props} > <Primitive.Indicator data-slot="radio-group-indicator" className="flex items-center justify-center" > <Circle aria-hidden="true" className="size-2 fill-current" /> </Primitive.Indicator> </Primitive.Item> ); } type RadioGroupOptionProps = React.ComponentProps<"label"> & { /** Heading shown beside the radio control. */ title: string; /** Supporting copy below the option heading. */ description?: string; /** Value submitted by the radio group. */ value: string; /** Disables this choice. */ disabled?: boolean; }; function RadioGroupOption({ className, title, description, value, disabled, children, ...props }: RadioGroupOptionProps) { return ( <label data-slot="radio-group-option" data-disabled={disabled || undefined} className={cn( "flex min-h-14 cursor-pointer items-start gap-3 rounded-lg border bg-card p-3 text-card-foreground shadow-xs transition-[border-color,background-color,box-shadow] duration-150 hover:bg-accent/50 has-[[data-state=checked]]:border-primary has-[[data-state=checked]]:bg-primary/5 has-[:focus-visible]:ring-[3px] has-[:focus-visible]:ring-ring/50 data-[disabled=true]:cursor-not-allowed data-[disabled=true]:opacity-50 motion-reduce:transition-none", className, )} {...props} > <RadioGroupItem value={value} disabled={disabled} className="mt-0.5" /> <span className="grid min-w-0 flex-1 gap-0.5"> <span className="text-sm font-medium">{title}</span> {description && ( <span className="text-sm leading-snug text-muted-foreground"> {description} </span> )} </span> {children} </label> ); } export { RadioGroup, RadioGroupItem, RadioGroupOption, type RadioGroupProps, type RadioGroupItemProps, type RadioGroupOptionProps, };Update the import paths to match your project setup.
$ pnpm dlx shadcn@latest add https://ui.ballmac.com/r/base/radio-group.jsonInstall the dependencies.
$ pnpm add lucide-react @base-ui/react@^1.9.0Add the Ballmac items it builds on (their Base UI versions where they have one).
$ pnpm dlx shadcn@latest add https://ui.ballmac.com/r/base/direction.json https://ui.ballmac.com/r/base/fieldset.jsonCopy the source into your project.
components/ballmac/radio-group.tsx// Ballmac UI: Radio Group. https://ui.ballmac.com/components/radio-group "use client"; import * as React from "react"; import { Circle } from "lucide-react"; import { Radio } from "@base-ui/react/radio"; import { RadioGroup as Primitive } from "@base-ui/react/radio-group"; import { DirectionProvider, useDirection } from "@/lib/ballmac/direction"; import { useFieldsetDisabled } from "@/lib/ballmac/fieldset"; import { cn } from "@/lib/utils"; type RadioGroupProps = Omit<React.ComponentProps<typeof Primitive>, "className" | "value" | "defaultValue" | "onValueChange"> & { className?: string; /** Reading direction for the arrow keys. Defaults to the page's. */ dir?: "ltr" | "rtl"; value?: string; defaultValue?: string; onValueChange?: (value: string) => void; }; function RadioGroup({ className, dir: dirProp, onValueChange, ...props }: RadioGroupProps) { const dir = useDirection(dirProp); return ( <DirectionProvider dir={dir}> <Primitive dir={dir} data-slot="radio-group" onValueChange={(v) => onValueChange?.(String(v))} className={cn("grid gap-2", className)} {...props} /> </DirectionProvider> ); } type RadioGroupItemProps = Omit<React.ComponentProps<typeof Radio.Root>, "className"> & { className?: string }; function RadioGroupItem({ className, disabled, ref, ...props }: RadioGroupItemProps) { const fieldset = useFieldsetDisabled<HTMLElement>(disabled, ref as React.Ref<HTMLElement>); return ( <Radio.Root ref={fieldset.ref} disabled={fieldset.disabled} data-slot="radio-group-item" className={cn( "aspect-square size-[var(--bm-check-size,calc(var(--spacing)*4))] shrink-0 rounded-full border border-input bg-background text-primary shadow-xs outline-none transition-[color,border-color,box-shadow] duration-150 focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 data-disabled:cursor-not-allowed data-disabled:opacity-50 data-checked:border-primary motion-reduce:transition-none", className, )} {...props} > <Radio.Indicator data-slot="radio-group-indicator" className="flex items-center justify-center" > <Circle aria-hidden="true" className="size-2 fill-current" /> </Radio.Indicator> </Radio.Root> ); } type RadioGroupOptionProps = React.ComponentProps<"label"> & { /** Heading shown beside the radio control. */ title: string; /** Supporting copy below the option heading. */ description?: string; /** Value submitted by the radio group. */ value: string; /** Disables this choice. */ disabled?: boolean; }; function RadioGroupOption({ className, title, description, value, disabled, children, ...props }: RadioGroupOptionProps) { return ( <label data-slot="radio-group-option" data-disabled={disabled || undefined} className={cn( "flex min-h-14 cursor-pointer items-start gap-3 rounded-lg border bg-card p-3 text-card-foreground shadow-xs transition-[border-color,background-color,box-shadow] duration-150 hover:bg-accent/50 has-[[data-checked]]:border-primary has-[[data-checked]]:bg-primary/5 has-[:focus-visible]:ring-[3px] has-[:focus-visible]:ring-ring/50 data-[disabled=true]:cursor-not-allowed data-[disabled=true]:opacity-50 motion-reduce:transition-none", className, )} {...props} > <RadioGroupItem value={value} disabled={disabled} className="mt-0.5" /> <span className="grid min-w-0 flex-1 gap-0.5"> <span className="text-sm font-medium">{title}</span> {description && ( <span className="text-sm leading-snug text-muted-foreground"> {description} </span> )} </span> {children} </label> ); } export { RadioGroup, RadioGroupItem, RadioGroupOption, type RadioGroupProps, type RadioGroupItemProps, type RadioGroupOptionProps, };Update the import paths to match your project setup.
Usage
import { RadioGroup, RadioGroupItem, RadioGroupOption } from "@/components/ballmac/radio-group"The full example is in the Code tab above.
Examples
Compact choices
Export format
import { RadioGroup, RadioGroupItem } from "@/components/ballmac/radio-group";
export default function RadioGroupStates() {
return (
<div className="w-full max-w-xs">
<p className="mb-3 text-sm font-medium">Export format</p>
<RadioGroup aria-label="Export format" defaultValue="pdf">
{[
{ value: "pdf", label: "PDF document" },
{ value: "csv", label: "CSV spreadsheet" },
{ value: "json", label: "JSON data" },
].map((option) => (
<label
key={option.value}
className="flex min-h-9 items-center gap-3 text-sm"
>
<RadioGroupItem value={option.value} />
{option.label}
</label>
))}
</RadioGroup>
</div>
);
}API reference
| Prop | Type | Default |
|---|---|---|
title*Heading shown beside the radio control. | string | — |
descriptionSupporting copy below the option heading. | string | — |
value*Value submitted by the radio group. | string | — |
disabledDisables this choice. | boolean | — |
Also accepts the standard attributes of its root element.
Accessibility
| Key | Action |
|---|---|
| Tab | Enters the radio group |
| Arrow keys | Moves and selects among enabled choices |
| Space | Selects the focused choice |
Quality scorecard
Every applicable check passes
Measured in Chromium 153.0.8010.12 on October 19, 2026, on version 1.0.1, across 2 examples.
Passed: Accessibility scan
No serious or critical issues in light and dark, on a phone and a desktop (axe-core 4.13.0, WCAG 2.1 AA and best-practice rules).
Passed: Small screens
No sideways scrolling at 360, 390 or 1280 px wide.
Passed: Reduced motion
No endless animation to begin with.
Passed: Right to left
Mirrors correctly in Arabic, Hebrew, Persian and Urdu layouts (0% of elements off the mirror, limit 15%).
Passed: Clean console
No console errors or React hydration errors while loading.
Passed: Keyboard
2 tab stops, each showing a visible change when it takes focus. 3 documented keys.
Not applicable: Loading, empty and error
Does not show data or take submissions.
Passed: Automated tests
Covered by radio-group.test.tsx.
For information: Footprint
1.2 KB of source (gzip) in 1 file. Installs radix-ui, lucide-react.
Automated checks find a subset of problems and do not replace testing with a screen reader and a keyboard in your own app. What they miss.
Use with AI
Choose exactly one option in a form; use descriptive card labels when choices need context. With the shadcn MCP server set up (guide), ask your agent:
Add the Ballmac UI Radio Group (@ballmac/radio-group) to this project with the shadcn MCP, then use it where it fits.
Use it for
- A few mutually exclusive preferences
- Pricing or delivery options with explanations
Not for
- Many options; use select
- Multiple selections; use checkbox or toggle-group
Registry JSON: https://ui.ballmac.com/r/radio-group.json
Credits
Free to use in personal and commercial projects.
- Registry
- @ballmac/directionshadcn/utils
Pairs well with
Label
An accessible form label built on Radix Label that dims itself when the paired peer control is disabled and never selects text on double-click.
Calendar
A date grid for one day, several days or a range, with month and year selects, week numbers, disabled rules and range-end styling, on React DayPicker.
Color Picker
A native color chooser paired with an editable hex field and a live swatch.
Combobox
A searchable single-choice select with groups, descriptions, keywords, clearable value, invalid state and hidden-input form submission.
Ballmac UI Pro
Need the whole screen, not one piece?
311 premium blocks (dashboards, settings, calendars, mail, shops, onboarding), a private shadcn registry and Figma tokens. Blocks that show data come with loading, empty and error states built in.
Not ready? Try three Pro blocks free
Leave your email and the blocks appear right here, ready to copy. Yours to use in any project.