ui/components/radio

Radio

Terminal-styled radio button and radio group for single-selection.

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { RadioGroup, RadioGroupItem } from "@/components/ui/radio";5 6 export default function RadioGroupDefault() {7   const [value, setValue] = useState("react");8 9   return (10     <RadioGroup value={value} onChange={setValue} label="Framework">11       <RadioGroupItem value="react" label="React" />12       <RadioGroupItem value="vue" label="Vue" />13       <RadioGroupItem value="svelte" label="Svelte" />14       <RadioGroupItem value="angular" label="Angular" />15     </RadioGroup>16   );17 }18

Installation

$pnpm exec dgadd add ui/radio

[Installs to]src/components/ui/radio[Item]ui/radio

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Usage

tsx

1 "use client";2 3 import { useState } from "react";4 import { RadioGroup, RadioGroupItem } from "@/components/ui/radio";5 6 export default function RadioGroupDefault() {7   const [value, setValue] = useState("react");8 9   return (10     <RadioGroup value={value} onChange={setValue} label="Framework">11       <RadioGroupItem value="react" label="React" />12       <RadioGroupItem value="vue" label="Vue" />13       <RadioGroupItem value="svelte" label="Svelte" />14       <RadioGroupItem value="angular" label="Angular" />15     </RadioGroup>16   );17 }18

Examples

Variants

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { RadioGroup, RadioGroupItem } from "@/components/ui/radio";5 6 export default function RadioGroupVariants() {7   const [size, setSize] = useState("md");8   const [plan, setPlan] = useState("pro");9 10   return (11     <div className="flex flex-col gap-6">12       <div>13         <div className="text-xs text-muted-foreground uppercase font-bold mb-2">14           Horizontal Layout15         </div>16         <RadioGroup value={size} onChange={setSize} orientation="horizontal" label="Size">17           <RadioGroupItem value="sm" label="Small" />18           <RadioGroupItem value="md" label="Medium" />19           <RadioGroupItem value="lg" label="Large" />20         </RadioGroup>21       </div>22       <div>23         <div className="text-xs text-muted-foreground uppercase font-bold mb-2">24           With Descriptions25         </div>26         <RadioGroup value={plan} onChange={setPlan} label="Plan">27           <RadioGroupItem value="free" label="Free" description="Basic features, limited usage" />28           <RadioGroupItem value="pro" label="Pro" description="All features, priority support" />29           <RadioGroupItem30             value="enterprise"31             label="Enterprise"32             description="Custom solutions"33             disabled34           />35         </RadioGroup>36       </div>37     </div>38   );39 }40

Highlight, Invalid, and Disabled

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { RadioGroup, RadioGroupItem } from "@/components/ui/radio";5 6 export default function RadioGroupStates() {7   const [highlighted, setHighlighted] = useState<string | null>("staging");8 9   return (10     <div className="flex flex-col gap-6">11       <div className="flex flex-col gap-2">12         <div className="text-xs text-muted-foreground uppercase font-bold">Keyboard highlight</div>13         <RadioGroup14           label="Environment"15           defaultValue="development"16           activationMode="manual"17           highlighted={highlighted}18           onHighlightChange={setHighlighted}19         >20           <RadioGroupItem value="development" label="Development" />21           <RadioGroupItem value="staging" label="Staging" />22           <RadioGroupItem value="production" label="Production" />23         </RadioGroup>24       </div>25       <div className="flex flex-col gap-2">26         <div className="text-xs text-muted-foreground uppercase font-bold">Invalid</div>27         <RadioGroup label="Environment" aria-invalid>28           <RadioGroupItem value="development" label="Development" />29           <RadioGroupItem value="staging" label="Staging" />30         </RadioGroup>31       </div>32       <div className="flex flex-col gap-2">33         <div className="text-xs text-muted-foreground uppercase font-bold">Disabled group</div>34         <RadioGroup label="Environment" defaultValue="production" disabled>35           <RadioGroupItem value="staging" label="Staging" />36           <RadioGroupItem value="production" label="Production" />37         </RadioGroup>38       </div>39     </div>40   );41 }42

API Reference

Radio

Name	Type	Default	Description
checked	boolean	—	Controlled checked state.
defaultChecked	boolean	false	Initial checked state for uncontrolled usage.
onChange	(checked: boolean) => void	—	Called when the boolean checked state changes.
value	string	"on"	Hidden native input value used for form submission.
name	string	—	Hidden native input name used for same-name radio behavior and form submission.
required	boolean	false	Marks the hidden native radio input as required.
label	ReactNode	—	Visible label associated with the custom radio.
description	ReactNode	—	Visible description wired with aria-describedby.
disabled	boolean	false	Disables the custom control and hidden input.
size	"sm" \| "md" \| "lg"	"md"	Selectable control size token.
variant	"x" \| "bullet"	"bullet"	Indicator style.

RadioGroup

Name	Type	Default	Description
value	string	—	Controlled selected value.
defaultValue	string	—	Initial selected value for uncontrolled usage.
onChange	(value: string) => void	—	Called when the selected value changes.
highlighted	string \| null	—	Controlled highlighted item value for keyboard navigation.
onHighlightChange	(value: string \| null) => void	—	Called when keyboard navigation highlights a new item or clears highlight.
onNavigate	(value: string, direction: "previous" \| "next" \| "first" \| "last") => void	—	Called when arrow, Home, or End navigation moves to an item.
onEnter	(value: string, event: KeyboardEvent) => void	—	Called when Enter commits the focused item.
orientation	"vertical" \| "horizontal"	"vertical"	Layout orientation. All four arrow keys still navigate per APG radio behavior.
activationMode	"automatic" \| "manual"	"automatic"	Automatic selects on arrow navigation; manual moves focus/highlight until Space or Enter commits.
wrap	boolean	true	Whether arrow-key navigation wraps at the first and last item.
keyboardNavigation	boolean	true	Enable built-in arrow-key navigation.
onNavigationBoundaryReached	(direction: "previous" \| "next", event: KeyboardEvent, key: string) => void	—	Called when non-wrapping navigation reaches the first or last item.
autoFocus	boolean	false	Focuses the highlighted, selected, or first enabled item when the group becomes active.
name	string	—	Shared hidden native input name for grouped form submission.
required	boolean	false	Requires one enabled item to be selected. All-disabled groups are exempt like native radios.
label	string	—	Visible group label rendered before the items. Also names the radiogroup unless aria-label overrides it.
aria-label	string	—	Explicit accessible name for the radiogroup. Overrides the visible label when supplied.
aria-labelledby	string	—	ID of an external element that labels this component. Composed with the visible label unless aria-label is supplied.

RadioGroupItem

Name	Type	Default	Description
valuerequired	string	—	Item value. Must be unique within the group.
labelrequired	ReactNode	—	Visible item label.
description	ReactNode	—	Visible item description wired with aria-describedby.
disabled	boolean	false	Disables the item.

Data attributes

Attribute	Applies to	Values	Description
data-state	Radio / RadioGroupItem	"checked" \| "unchecked"	Boolean visual state for styling the custom control.
data-disabled	Radio / RadioGroupItem	present when disabled	Marks disabled radios.
data-highlighted	Radio / RadioGroupItem	present when highlighted	Marks the current keyboard-highlighted group item.
data-value	Radio / RadioGroupItem	item value	Stable value used by group navigation and form submission wiring.
data-diffgazer-selectable-owner	RadioGroup	"radio"	Scopes nested selectable-item discovery for keyboard navigation.

Accessibility

Keyboard Navigation

All four arrow keys, plus the vim aliases j/k, move focus and select items in automatic activation mode (per WAI-ARIA APG). Manual activation mode moves focus and emits onNavigate without changing value. Space selects the focused item. Enter commit via onEnter is a Diffgazer extension for preview/commit flows. Home/End jump to first/last item. Composite UIs can opt into initial focus with autoFocus, suspend RadioGroup-managed key handling with keyboardNavigation, and listen for onNavigationBoundaryReached(direction, event, key).

Key	Action
ArrowUp / ArrowLeft / k	Moves focus to the previous enabled radio; automatic mode also selects it.
ArrowDown / ArrowRight / j	Moves focus to the next enabled radio; automatic mode also selects it.
Home / End	Moves focus to the first or last enabled radio and selects it in automatic mode.
Space	Selects the focused radio.
Enter	Calls onEnter for preview/commit flows, or selects when wired.

Arrow navigation in both orientations

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { RadioGroup, RadioGroupItem } from "@/components/ui/radio";5 6 export default function RadioGroupVariants() {7   const [size, setSize] = useState("md");8   const [plan, setPlan] = useState("pro");9 10   return (11     <div className="flex flex-col gap-6">12       <div>13         <div className="text-xs text-muted-foreground uppercase font-bold mb-2">14           Horizontal Layout15         </div>16         <RadioGroup value={size} onChange={setSize} orientation="horizontal" label="Size">17           <RadioGroupItem value="sm" label="Small" />18           <RadioGroupItem value="md" label="Medium" />19           <RadioGroupItem value="lg" label="Large" />20         </RadioGroup>21       </div>22       <div>23         <div className="text-xs text-muted-foreground uppercase font-bold mb-2">24           With Descriptions25         </div>26         <RadioGroup value={plan} onChange={setPlan} label="Plan">27           <RadioGroupItem value="free" label="Free" description="Basic features, limited usage" />28           <RadioGroupItem value="pro" label="Pro" description="All features, priority support" />29           <RadioGroupItem30             value="enterprise"31             label="Enterprise"32             description="Custom solutions"33             disabled34           />35         </RadioGroup>36       </div>37     </div>38   );39 }40

Notes

Requires @diffgazer/keys (package mode)

RadioGroup's roving keyboard navigation imports from the required @diffgazer/keys peer. Package consumers must install @diffgazer/keys with @diffgazer/ui; packages are not yet published to npm, so until the first release install both from locally packed tarballs. Importing @diffgazer/ui/components/radio without keys fails at module load with an error naming the missing @diffgazer/keys package. Copy/dgadd consumers do not need the package — copy mode rewrites the keyboard hooks to local source.

Composition Contract

Prefer importing RadioGroup and RadioGroupItem for shadcn-like code. RadioGroup.Item is the same item component exposed for Radix-like namespacing. Use either form inside RadioGroup, directly or through your own wrapper components. Every item value must be unique within a group because selection, highlighting, and form output are value-based.

Standalone vs RadioGroup

Standalone same-name Radio components stay mutually exclusive via a document-level event, but they are form-submission-only: there is no arrow-key navigation and each radio is its own tab stop. For a keyboard-complete group (roving focus, arrow navigation, a single tab stop), use RadioGroup.

Keyboard Navigation

RadioGroup delegates roving focus to @diffgazer/keys navigation. All four arrow keys move focus and select items by default regardless of orientation (per WAI-ARIA APG radio group pattern). Home/End jump to first/last item. Space selects the focused item. Enter commit is a Diffgazer extension for preview/commit flows, not the APG baseline. Use activationMode="manual" with onNavigate/onChange when arrows should move focus and highlight without changing value, and onEnter when Enter should commit the focused item. Use autoFocus to focus the highlighted, selected, or first enabled item when the group becomes active. Use keyboardNavigation to suspend RadioGroup-managed key handling; when suspended, enabled items remain tabbable. Use onNavigationBoundaryReached(direction, event, key) to hand focus to adjacent controls and filter vertical-only handoffs by key when needed.

Glyph Hierarchy

The brackets are chrome and render muted; the inner mark keeps the control's tone at bold weight, so a selected row is the only place full-contrast ink appears in the glyph column. The visible text is unchanged and the whole cell stays aria-hidden.

Indicator Variants

variant='bullet' (default) marks the selected state with [●]; variant='x' marks it with [x]. Both glyphs are three characters, the same width Checkbox reserves, so a form mixing radios and checkboxes keeps one label left edge at every size.

Orientation

Set orientation='horizontal' for inline layouts. Layout direction changes but all four arrow keys always navigate (per APG spec).

Required validation

A required RadioGroup participates in native validation only while it has an enabled item. If every item is disabled, the group follows native radio behavior: it is valid, omits aria-required and derived invalid state, contributes no value, and has no validation focus target.

Source

Install via CLI: pnpm exec dgadd add ui/radio. Keyboard hooks are included as standalone copies. For the full experience, use --integration keys.

Highlighted source loads after this disclosure opens. Browse the source repository.

Radio

Installation

Usage

Examples

Variants

Highlight, Invalid, and Disabled

API Reference

Radio

RadioGroup

RadioGroupItem

Data attributes

Accessibility

Keyboard Navigation

Arrow navigation in both orientations

Notes

Requires @diffgazer/keys (package mode)

Composition Contract

Standalone vs RadioGroup

Keyboard Navigation

Glyph Hierarchy

Indicator Variants

Orientation

Required validation

Source

View component source (31 files)