Radio
Choose one option from a related set.
Overview
RadioGroup lets the user pick one option from a visible, related set using native radio inputs. It owns the shared question, selected value, and browser form behavior.
onValueChange, not onCheckedChange. Set checked, defaultChecked, name, and form on RadioGroup, not a grouped Radio; values are strings.Use when
The user chooses exactly one visible option from a related set.
Use instead
Use Select when there are more than ~5–7 options. Use Switch for an on/off setting that applies immediately.
Usage
import { Radio, RadioGroup } from "@smoothie-framework/whisk-react";
<RadioGroup name="visibility" label="Project visibility" defaultValue="team">
<Radio value="team" label="Team" />
<Radio value="private" label="Private" />
</RadioGroup>Examples
Variants
RadioGroup does not set a variant. Apply the same variant to every option in the group.
import { Radio, RadioGroup, Stack } from "@smoothie-framework/whisk-react";
<Stack gap={4}>
<RadioGroup label="Solid" defaultValue="team">
<Radio value="team" variant="solid" label="Team" />
<Radio value="private" variant="solid" label="Private" />
</RadioGroup>
<RadioGroup label="Subtle" defaultValue="team">
<Radio value="team" variant="subtle" label="Team" />
<Radio value="private" variant="subtle" label="Private" />
</RadioGroup>
<RadioGroup label="Outline" defaultValue="team">
<Radio value="team" variant="outline" label="Team" />
<Radio value="private" variant="outline" label="Private" />
</RadioGroup>
</Stack>Sizes
RadioGroup does not set a size. Apply the same size to every option in the group.
import { Radio, RadioGroup, Stack } from "@smoothie-framework/whisk-react";
<Stack gap={4}>
<RadioGroup label="Small" defaultValue="team">
<Radio value="team" size="sm" label="Team" />
<Radio value="private" size="sm" label="Private" />
</RadioGroup>
<RadioGroup label="Medium" defaultValue="team">
<Radio value="team" size="md" label="Team" />
<Radio value="private" size="md" label="Private" />
</RadioGroup>
<RadioGroup label="Large" defaultValue="team">
<Radio value="team" size="lg" label="Team" />
<Radio value="private" size="lg" label="Private" />
</RadioGroup>
</Stack>States
Set disabled, readOnly, and invalid on RadioGroup when the whole decision shares the state. Set disabled on an individual Radio when one option is unavailable.
import { Radio, RadioGroup, Stack } from "@smoothie-framework/whisk-react";
<Stack gap={4}>
<RadioGroup label="Disabled" defaultValue="team" disabled>
<Radio value="team" label="Team" />
<Radio value="private" label="Private" />
</RadioGroup>
<RadioGroup label="Delivery speed" defaultValue="standard">
<Radio value="standard" label="Standard" />
<Radio value="priority" label="Priority" disabled />
</RadioGroup>
<RadioGroup label="Read-only" defaultValue="team" readOnly>
<Radio value="team" label="Team" />
<Radio value="private" label="Private" />
</RadioGroup>
<RadioGroup
label="Billing frequency"
invalid
error="Choose a billing frequency to continue."
>
<Radio value="monthly" label="Monthly" />
<Radio value="yearly" label="Yearly" />
</RadioGroup>
</Stack>Label position
Use start labels consistently when a settings layout needs the controls aligned at its trailing edge.
import { Radio, RadioGroup } from "@smoothie-framework/whisk-react";
<RadioGroup
label="Default project visibility"
description="Choose the setting used for new projects."
defaultValue="team"
>
<Radio value="team" label="Team" labelPosition="start" />
<Radio value="private" label="Private" labelPosition="start" />
</RadioGroup>Controlled
Use value and onValueChange when application state owns the selected option.
Selected: team
import { useState } from "react";
import { Radio, RadioGroup, Stack, Text } from "@smoothie-framework/whisk-react";
export function VisibilitySetting() {
const [visibility, setVisibility] = useState("team");
return (
<Stack gap={2}>
<RadioGroup
label="Project visibility"
value={visibility}
onValueChange={setVisibility}
>
<Radio value="team" label="Team" />
<Radio value="private" label="Private" />
</RadioGroup>
<Text textStyle="body-sm">Selected: {visibility}</Text>
</Stack>
);
}Forms
Use react-hook-form with value and onValueChange. For a plain <form>, name and required submit the selected value without extra state.
import { Controller, useForm } from "react-hook-form";
import { Box, Button, Radio, RadioGroup, Stack } from "@smoothie-framework/whisk-react";
type BillingValues = { billing: string };
function onSubmit(values: BillingValues) {
// Save values in your application.
}
export function BillingForm() {
const { control, handleSubmit } = useForm<BillingValues>();
return (
<Box as="form" noValidate onSubmit={handleSubmit(onSubmit)}>
<Stack gap={3}>
<Controller
name="billing"
control={control}
rules={{ required: "Choose a billing frequency to continue." }}
render={({ field, fieldState }) => (
<RadioGroup
label="Billing frequency"
name={field.name}
required
value={field.value}
onValueChange={field.onChange}
invalid={!!fieldState.error}
error={fieldState.error?.message}
>
<Radio value="monthly" label="Monthly" />
<Radio value="yearly" label="Yearly" />
</RadioGroup>
)}
/>
<Button type="submit">Continue</Button>
</Stack>
</Box>
);
}Plan options
Radio has no built-in card treatment. Compose plan details with its renderable label and description props.
import { Radio, RadioGroup } from "@smoothie-framework/whisk-react";
<RadioGroup label="Choose a plan" defaultValue="starter">
<Radio
value="starter"
label="Starter"
description="$0/month · For personal projects and evaluation."
/>
<Radio
value="team"
label="Team"
description="$24/month · For teams that need shared workspaces."
/>
</RadioGroup>Group
Use a horizontal group only for short peer options that remain easy to scan at narrow widths.
import { Radio, RadioGroup } from "@smoothie-framework/whisk-react";
<RadioGroup
label="Density"
description="Choose the spacing used in this workspace."
orientation="horizontal"
defaultValue="comfortable"
>
<Radio value="compact" label="Compact" />
<Radio value="comfortable" label="Comfortable" />
</RadioGroup>Props
RadioGroup props
Radio props
Shared props
Accessibility
RadioGroup renders a native fieldset and legend for the shared question. Tab enters the group on its checked option, or its first option when none is selected; Arrow keys move and wrap through options, and Space selects the focused option. Do not use radios to trigger immediate actions—use Button or Switch instead. Keep every item label short, distinct, and visible, and use an item description only when it explains a decision-relevant difference.
Content guidance
Name the decision, then use short parallel labels for every option. Preselect the safe or recommended default when one exists; otherwise leave the group unselected so the user makes the choice deliberately.