RadioGroup | Fragments

Preview

<RadioGroup defaultValue="option1" label="Select an option">
  <RadioGroup.Item value="option1" label="Option 1" />
  <RadioGroup.Item value="option2" label="Option 2" />
  <RadioGroup.Item value="option3" label="Option 3" />
</RadioGroup>

Installation

npx @usefragments/cli add radiogroup

Writes src/fragments/ui/components/RadioGroup plus what it imports, the globals stylesheet, and .fragments/registry-lock.json, then prints the packages to add. No account, no key.

Your own registry: publish from Fragments Cloud and add --registry org/name. Connect a workspace.

Anatomy

RadioGroup is a compound: import the root and reach its parts through dot notation.

RadioGroup.Item

Three options stacked, the first already chosen.

<RadioGroup defaultValue="option1" label="Select an option">
  <RadioGroup.Item value="option1" label="Option 1" />
  <RadioGroup.Item value="option2" label="Option 2" />
  <RadioGroup.Item value="option3" label="Option 3" />
</RadioGroup>

Examples

With Helper Text

Each option carries the trade-off under its label.

<RadioGroup defaultValue="standard" label="Shipping Method">
  <RadioGroup.Item
    value="standard"
    label="Standard"
    helperText="5-7 business days"
  />

Horizontal

One row — good for short labels like sizes.

<RadioGroup orientation="horizontal" defaultValue="small" label="Size">
  <RadioGroup.Item value="small" label="S" />
  <RadioGroup.Item value="medium" label="M" />
  <RadioGroup.Item value="large" label="L" />
  <RadioGroup.Item value="xlarge" label="XL" />
</RadioGroup>

With Group Helper Text

One note under the whole group instead of per option.

<RadioGroup defaultValue="standard" label="Plan" helperText="You can change your plan at any time">
  <RadioGroup.Item value="free" label="Free" />
  <RadioGroup.Item value="standard" label="Standard" />
  <RadioGroup.Item value="pro" label="Pro" />
</RadioGroup>

With Error

Passing a string to error tints the group and prints the reason.

<RadioGroup label="Required selection" error="Please select an option">
  <RadioGroup.Item value="a" label="Option A" />
  <RadioGroup.Item value="b" label="Option B" />
</RadioGroup>

Disabled

The choice stays visible but nothing can change it.

<RadioGroup disabled defaultValue="locked" label="Locked selection">
  <RadioGroup.Item value="locked" label="This is locked" />
  <RadioGroup.Item value="other" label="Cannot select" />
</RadioGroup>

Styling Targets

Named class hooks for the wrapper, the group, and each item.

<RadioGroup
  defaultValue="a"
  label="Display mode"
  wrapperClassName="demo-radio-wrapper"
  groupClassName="demo-radio-group"
>

API

Component props
Prop	Type	Default	Description
`value`	`string`	Not set	Controlled selected value
`defaultValue`	`string`	Not set	Default value (uncontrolled)
`onValueChange`	`function`	Not set	Callback when selection changes
`onChange`	`function`	Not set	Alias for onValueChange
`orientation`	`enumhorizontalvertical`	`vertical`	Layout orientation
`disabled`	`boolean`	`false`	Disable all options
`name`	`string`	Not set	Form field name
`label`	`string`	Not set	Group label
`helperText`	`string`	Not set	Helper text shown below the group
`error`	`union`	Not set	Show error styling. When a string is provided, it is displayed as an error message.
`size`	`enumsmmdlg`	`md`	Size variant
`variant`	`enumoutline`	Not set	Chrome. Omit for the inline radio beside its label; 'outline' renders each item as a full-width bordered surface with the radio tucked inside.
`wrapperClassName`	`string`	Not set	Class name for the outer wrapper element
`groupClassName`	`string`	Not set	Class name for the inner radio group element
`groupId`	`string`	Not set	ID for the inner element with role=radiogroup; the inherited id remains on the outer field wrapper
`children`Required	`node`	Not set	RadioGroup.Item elements
`form`	`string`	Not set	ID of the form that owns the radio inputs
`inputRef`	`union`	Not set	Ref to the hidden input element
`readOnly`	`boolean`	`false`	Whether the selected value cannot be changed by the user
`required`	`boolean`	`false`	Whether the user must choose a value before submitting a form

Accessibility

The group carries its own label
Arrow keys move between options
The selected option reads as checked

Standards

Guidance

Use when

Exactly one answer out of two to five
Options rule each other out
Every option should be visible without opening anything

Avoid when

Several answers allowed (use a Checkbox group)
Long lists (use Select)
A single on/off (use Switch)
Options need searching (use Combobox)

CheckboxalternativeUse Checkbox for multiple selections
SelectalternativeUse Select for many options or limited space
SwitchalternativeUse Switch for binary on/off choices

Next steps

Accessibility contractThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.