Radio

Patterns

Simple Choice Group

When to use:

• A small visible set of mutually exclusive options belongs in a form.

Composition notes:

• Keep all related radios under the same name.
• Wrap control and label text together so the full row stays clickable.

Trade-offs:

• Strong native form semantics.
• Weaker fit for dense button-like choice UIs.

import { Fieldset, FieldsetLegend, Radio } from '@vega-ui/react';

const methods = [
  { value: 'standard', label: 'Standard · 5–7 business days · Free' },
  { value: 'express', label: 'Express · 2–3 business days · $9.90' },
  { value: 'overnight', label: 'Overnight · next business day · $24.00' },
];

export default function LabeledRadioOption() {
  return (
    <Fieldset>
      <FieldsetLegend style={{ marginBlockEnd: 'var(--spacing-5)' }}>Shipping method</FieldsetLegend>

Settings Choice Group

When to use:

• Users must choose one persistent mode or policy from a short list.

Composition notes:

• Give the group a surrounding label or fieldset-level context.
• Keep option labels descriptive rather than action-oriented.

Trade-offs:

• Easy to understand in forms.
• Less compact than SegmentedControl when all options should read as adjacent buttons.

import { Fieldset, FieldsetLegend, Radio, Text } from '@vega-ui/react';

const policies = [
  {
    value: 'anyone',
    label: 'Anyone with the link',
    description: 'People outside your organization can open shared documents without signing in.',
  },
  {
    value: 'organization',
    label: 'People in Acme Corp',
    description: 'Only signed-in members of your organization can open shared documents.',

Radio Choice In Overlays

When to use:

• An overlay asks for one required decision before continuing.

Composition notes:

• Keep the list short and scannable.
• Combine with clear dialog or drawer copy so the group meaning is obvious.

Trade-offs:

• Keeps the choice explicit.
• Can feel verbose if there are too many options.

import { CSSProperties, FormEvent, useState } from 'react';
import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogTrigger,
  Fieldset,
  FieldsetLegend,
  Heading,
  Icon,
  IconButton,

Comparison

Quick Decision Rule

Use Radio when exactly one option from a small visible set must be chosen.

Radio vs Checkbox

Use Radio when:

• exactly one option should be selected

Use Checkbox when:

• options can be selected independently or in combination

Main trade-off: radios enforce exclusivity, while checkboxes support independent selection.

Radio vs Switch

Use Radio when:

• the user is choosing one option from a set

Use Switch when:

• the control represents one immediate binary setting

Main trade-off: radios compare alternatives, while switches toggle one setting on or off.

Radio vs SegmentedControl

Use Radio when:

• a simple visible group is enough
• native form semantics matter more than always-visible button-like presentation

Use SegmentedControl when:

• all options should stay visible as adjacent segments with a stronger selected-state treatment

Main trade-off: radios stay simpler and more form-like, while segmented controls are more visually explicit.

Radio vs CheckboxCard

Use Radio when:

• exclusive options can stay compact and form-like

Use CheckboxCard when:

• the options are independent and each one needs richer descriptive content

Choose This Component When

• One option from a small set must be selected.
• The group belongs naturally in a form.
• Native radio semantics are the right fit.
• the UI should read as exclusive choice rather than an immediate toggle

Do Not Choose This Component When

• Options can be selected independently.
• The control is a single immediate binary setting.
• The feature needs a denser always-visible segmented UI.

Troubleshooting

Several Radios Can Be Checked At Once

Symptom

Multiple options appear selected even though the UI is supposed to allow only one choice.

Likely Cause

The radios do not share the same native name.

How To Verify

• Inspect the rendered name attribute.
• Check whether all options in the group use the same value.

Fix

• Give all related radios the same name.
• Keep unrelated groups separated by different names.

Only The Tiny Control Feels Clickable

Symptom

Users miss the label row because only the radio circle feels interactive.

Likely Cause

The visible text is not wrapped into the same clickable label structure.

How To Verify

• Hover and click on the text next to the control.
• Inspect whether the label wraps both the radio and the text.

Fix

• Use a wrapping label for the control and its text.
• Keep the full row clickable when possible.

Radio Was Used For The Wrong Selection Model

Symptom

The UI works technically, but users expect to select multiple items or toggle one setting independently.

Likely Cause

Radio was chosen where Checkbox or Switch would better match the product model.

How To Verify

• Check whether the choice is exclusive, independent, or binary.
• Compare the flow with other selection controls in the system.

Fix

• Use Checkbox for independent choices.
• Use Switch for one immediate binary setting.