Skip to content
Browse documentation
whisk/ui

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.

Coming from another library?
Use RadioGroup 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

Project visibility
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.

Solid
Subtle
Outline
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.

Small
Medium
Large
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.

Disabled
Delivery speed
Read-only
Billing frequency
Choose a billing frequency to continue.
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.

Default project visibility
Choose the setting used for new projects.
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.

Project visibility

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.

Billing frequency
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.

Choose a plan
$0/month · For personal projects and evaluation.$24/month · For teams that need shared workspaces.
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.

Density
Choose the spacing used in this workspace.
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

PropTypeDefaultDescription
labelReactNodenoneName the related set of options.
descriptionReactNodenoneAdd context for the whole choice.
errorReactNodenoneShow validation feedback when the group is invalid.
valuestringnoneControl the selected option. Do not provide defaultValue at the same time.
defaultValuestringnoneInitialize the selected option without controlling later changes.
onValueChange(value: string) => voidnoneReceive the newly selected option value.
namestringgenerated group IDName grouped radios for native form submission.
formstringnoneAssociate the fieldset with a native form by ID.
requiredbooleanfalseRequire one selection before native form submission.
orientationvertical | horizontalverticalArrange the visible options in a column or compact row.
invalidbooleanfalseExpose invalid state and associate the error when present.
disabledbooleanfalseDisable every option in the group.
readOnlybooleanfalseKeep the current selection visible without allowing changes.

Radio props

PropTypeDefaultDescription
valuestringnoneProvide one unique, stable value within RadioGroup.
labelReactNodenoneName the option.
descriptionReactNodenoneExplain a decision-relevant difference for this option.
labelPositionstart | endendPlace every option label before or after its indicator.
variantsolid | subtle | outlinesolidChoose the option's visual treatment. RadioGroup does not set this value.
sizesm | md | lgmdChoose the option's control size. RadioGroup does not set this value.
disabledbooleanfalseDisable this option while leaving the other options available.
invalidbooleanfalseExpose invalid state for a standalone Radio; set invalid on RadioGroup for a group.
readOnlybooleanfalseKeep a standalone Radio visible without allowing its state to change.

Shared props

PropSupportedNotes
as / asChildNoRadio owns its native input and visual control structure.
Style propsNoRadio exposes semantic form and appearance props instead of the shared style-prop surface. See Style props.
className / styleYesApplied to the visual radio root.
refYesForwards to the native input.
Native HTML attributesYesNative input attributes are forwarded, except Radio-owned type, grouped selection, and ARIA attributes.

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.

DoDon't
label="Billing frequency" with Monthly and Yearlylabel="Choose one" with non-parallel options