# Radio ## Summary `Radio` is the single-choice selection control for mutually exclusive options that share the same `name`. It is the most form-like exclusive-choice primitive in the selection family. ## Imports ```tsx import { Radio, type RadioProps, type RadioSize, type RadioVariant, } from '@vega-ui/react'; ``` ## Exported Types - `RadioProps` - `RadioSize` - `RadioVariant` ## Minimal Composition ```tsx import { Radio } from '@vega-ui/react'; export default function MinimalComposition() { return (

Light Dark

); } ``` ## Required Parts - `Radio`: native radio input surface ## Optional Parts - No extra public parts beyond the input itself ## Composition Order 1. visible label wrapper 2. `Radio` 3. label text ## Variants - Sizes: `sm`, `md`, `lg` - Variants: `primary`, `secondary` - States: unchecked, checked, disabled, checked-disabled ## Edge Cases - Radios only behave as one group when the consumer gives related inputs the same `name`. - Labels should describe the option, not the action of clicking it. - Radios are the wrong choice for independent boolean settings. - If options need richer descriptions or tile-sized targets, `SegmentedControl` or `CheckboxCard` may be clearer depending on exclusivity. ## Common Mistakes - Using radios without a shared `name`. - Using radios for multi-select choices. - Building a radio row where only the tiny control is clickable. ## Examples ### Basic #### Basic: choice group in a fieldset `Radio` is a bare native `input[type='radio']`, so each one is wrapped in a `` with its text. Radios with the same `name` form one group: only one can be checked, and arrow keys move between them. `Fieldset` with a legend names the group. ```tsx 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 (

Shipping method

{methods.map((method) => ( {method.label} ))}

); } ``` ### Controlled/Stateful #### Controlled/Stateful: selected value in the parent The parent stores the selected value and passes `checked={cycle === item.value}` to every radio; `onChange` reads `event.currentTarget.value`. The price below is computed from the same state. ```tsx import { useState } from 'react'; import { Fieldset, FieldsetLegend, Radio, Text } from '@vega-ui/react'; const cycles = [ { value: 'monthly', label: 'Monthly', perMonth: 15 }, { value: 'yearly', label: 'Yearly (2 months free)', perMonth: 12.5 }, ]; export default function ParentOwnedSelectedPlan() { const [cycle, setCycle] = useState('yearly'); const selected = cycles.find((item) => item.value === cycle) ?? cycles[0]; const seats = 8; const total = selected.perMonth * seats; return (

Billing cycle

{cycles.map((item) => ( setCycle(event.currentTarget.value)} /> {item.label} ))}

{seats} seats × ${selected.perMonth.toFixed(2)} = ${total.toFixed(2)} per month

); } ``` ### Form/Integration #### Form/Integration: required group and FormData `required` on the radios makes the whole group required, so the browser blocks submit until one is chosen. `FormData.get('size')` returns the checked `value`; reset clears the selection. ```tsx import { FormEvent, useState } from 'react'; import { Button, Fieldset, FieldsetLegend, Radio, Text } from '@vega-ui/react'; const sizes = [ { value: 's-2vcpu-4gb', label: '2 vCPU · 4 GB RAM · $24/mo' }, { value: 's-4vcpu-8gb', label: '4 vCPU · 8 GB RAM · $48/mo' }, { value: 's-8vcpu-16gb', label: '8 vCPU · 16 GB RAM · $96/mo' }, ]; export default function FormDataSubmission() { const [result, setResult] = useState(''); const handleSubmit = (event: FormEvent) => { event.preventDefault(); const data = new FormData(event.currentTarget); setResult(`size=${data.get('size')}`); }; return ( ); } ``` ### Layout/Overlay #### Layout/Overlay: choice inside a dialog The radios live in a `form method='dialog'`: saving reads `FormData`, updates the value outside and closes the dialog. Reopening starts from the saved value because the content remounts. ```tsx import { CSSProperties, FormEvent, useState } from 'react'; import { Button, Dialog, DialogClose, DialogContent, DialogTrigger, Fieldset, FieldsetLegend, Heading, Icon, IconButton, Radio, Text, } from '@vega-ui/react'; import { XIcon } from '@vega-ui/icons'; const environments = [ { value: 'preview', label: 'Preview' }, { value: 'staging', label: 'Staging' }, { value: 'production', label: 'Production' }, ]; export default function RadioChoiceInOverlays() { const [environment, setEnvironment] = useState('staging'); const handleSubmit = (event: FormEvent) => { const data = new FormData(event.currentTarget); setEnvironment(String(data.get('environment'))); }; return (

Deploy target: {environment}

); } ``` ### Error #### Error: required group without a selection The `invalid` event of the required radios replaces the browser bubble: the error is linked to the `Fieldset` through `aria-describedby`, the radios get `aria-invalid`, and focus moves to the first option. Choosing any option clears the error. ```tsx import { FormEvent, useRef, useState } from 'react'; import { Button, Fieldset, FieldsetLegend, HelperText, Radio } from '@vega-ui/react'; const reasons = [ { value: 'price', label: 'It is too expensive' }, { value: 'features', label: 'It is missing features I need' }, { value: 'switching', label: 'I am switching to another product' }, { value: 'other', label: 'Other' }, ]; export default function MissingRequiredRadioSelection() { const [invalid, setInvalid] = useState(false); const [done, setDone] = useState(false); const firstRef = useRef(null); const handleInvalid = (event: FormEvent) => { event.preventDefault(); firstRef.current?.focus(); setInvalid(true); }; const handleSubmit = (event: FormEvent) => { event.preventDefault(); setDone(true); }; return ( ); } ``` ### Disabled #### Disabled: disabled option and disabled group A single unavailable option is `disabled` and explains why through `aria-describedby`. A `Fieldset disabled` disables every radio inside natively. The label text is dimmed by the example, because `Radio` only styles the input. Disabled radios are not submitted. ```tsx import { Fieldset, FieldsetLegend, HelperText, Radio } from '@vega-ui/react'; export default function DisabledOption() { return (

Data region

European Union (Frankfurt) United States (Virginia)

Australia (Sydney) Opens in Q3. Join the waitlist in Settings → Regions.

Backup frequency Managed by your organization policy.

Daily Hourly

); } ``` ### Edge #### Edge: options with long descriptions When each option has a description, the label is linked with `htmlFor`/`id`, the description through `aria-describedby`, and the radio is aligned to the first line with `flex-start` and `flex-shrink: 0` so long text does not squeeze it. ```tsx 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.', }, { value: 'invited', label: 'Invited people only', description: 'Every document must be shared with each person by email. Existing links stop working.', }, ]; export default function OptionsWithDescriptions() { return (

Link sharing

{policies.map((policy) => (

))}

); } ``` #### Edge: repeated groups need unique names Every table row is its own group, so each row gets its own `name` built from the row id; a shared name would turn the whole table into one group. Radios without visible text get an `aria-label` that names both the row and the option. ```tsx import { useState } from 'react'; import { Radio, Table, TableBody, TableData, TableHead, TableHeading, TableRow } from '@vega-ui/react'; const members = [ { id: 'u-201', name: 'Maya Chen' }, { id: 'u-202', name: 'Lucas Ferreira' }, { id: 'u-203', name: 'Aisha Okafor' }, ]; const roles = ['viewer', 'editor', 'admin']; export default function RepeatedGroupsUniqueNames() { const [assigned, setAssigned] = useState>({ 'u-201': 'admin', 'u-202': 'editor', 'u-203': 'viewer' }); const assign = (memberId: string, role: string) => { setAssigned({ ...assigned, [memberId]: role }); }; return ( Member {roles.map((role) => ( {role} ))} {members.map((member) => ( {member.name} {roles.map((role) => ( assign(member.id, role)} /> ))} ))}

); } ``` ## Anatomy ### Overview `Radio` is a single native input rather than a multi-part compound component. The real composition contract lives in how multiple radios are grouped through shared `name` and visible labels. ### Required Parts #### `Radio` Required. Renders the native `input[type='radio']` and owns checked, disabled, size, and variant behavior. ### Optional Parts `Radio` does not expose additional public child parts. ### Composition Order 1. visible label wrapper 2. `Radio` 3. label text ### Valid Composition Patterns Two valid ways to name a radio: wrap it in a `` together with its text, or give it an `id` and point a separate `Label` at it with `htmlFor`. Both radios share one `name`, so they form one group. ```tsx import { Label, Radio } from '@vega-ui/react'; export default function ValidCompositionPatterns() { return (

Comfortable

Compact

); } ``` ### Invalid Composition Patterns #### Radios without a shared `name` This breaks mutually exclusive group behavior. #### Radio used as a standalone boolean toggle If the choice is independent rather than exclusive, use `Checkbox` or `Switch`. #### Label text detached from the control This makes the radio harder to understand and harder to click.