Skip to main content

RadioGroup

One choice from a few options that are all visible at once. Each option is a RadioGroupItem.

import { RadioGroup, RadioGroupItem } from 'patine-ui';

The quickest way: give RadioGroup its options, each { value, label, description?, disabled? }.

Loading…
<RadioGroup
  defaultValue="standard"
  aria-label="Shipping"
  options={[
    { value: 'standard', label: 'Standard', description: '4–6 business days' },
    { value: 'express', label: 'Express', description: '1–2 business days' },
    { value: 'pickup', label: 'Pick up in store', disabled: true },
  ]}
/>

Compose the parts​

For full control, leave options out and put a RadioGroupItem for each option inside.

Loading…
<RadioGroup value={plan} onValueChange={setPlan} aria-label="Plan">
  <RadioGroupItem value="free" label="Free" description="The core components" />
  <RadioGroupItem value="pro" label="Pro" description="Charts, scheduler and data grid" />
  <RadioGroupItem value="team" label="Team" description="Five seats and priority support" />
</RadioGroup>

Try the props​

Props
orientation
design
<RadioGroup defaultValue="express" aria-label="Delivery">
…
</RadioGroup>

Example: choose a plan​

Each option's label and description can be any node, such as a price beside the name. Here the choice also drives the button below it.

Loading…
<Card style={{ maxWidth: 420, width: '100%' }}>
  <CardHeader>
    <CardTitle>Choose a plan</CardTitle>
  </CardHeader>
  <CardContent>
    <RadioGroup value={plan} onValueChange={setPlan} aria-label="Plan">
      {PLANS.map((p) => (
        <RadioGroupItem
          key={p.value}
          value={p.value}
          label={
            <HStack gap="sm" align="center">
              <Text weight="medium">{p.name}</Text>
              <Text color="textSecondary">{p.price}</Text>
              {p.badge ? <Badge variant="success">{p.badge}</Badge> : null}
            </HStack>
          }
          description={p.note}
          accessibilityLabel={`${p.name}, ${p.price}`}
        />
      ))}
    </RadioGroup>
  </CardContent>
  <CardFooter>
    <Button style={{ flex: 1 }}>{`Continue with ${chosen?.name}`}</Button>
  </CardFooter>
</Card>

Disabled options​

disabled on an item skips it; on the group it disables them all.

Loading…
<RadioGroup defaultValue="standard" aria-label="Shipping">
  <RadioGroupItem value="standard" label="Standard" description="3 to 5 days" />
  <RadioGroupItem value="express" label="Express" description="Next day" />
  <RadioGroupItem value="pickup" label="Store pickup" description="Not available in your area" disabled />
</RadioGroup>

Horizontal​

orientation="horizontal" lays short options out in a row, such as a size or a rating scale. The arrow keys still move through them.

Loading…
<VStack gap="xs">
  <Text weight="medium">Size</Text>
  <RadioGroup
    orientation="horizontal"
    defaultValue="m"
    aria-label="Size"
    options={['XS', 'S', 'M', 'L', 'XL'].map((size) => ({ value: size.toLowerCase(), label: size, disabled: size === 'XS' }))}
  />
</VStack>

Required choice​

A radio group doesn't check itself: show an error from your form when nothing is picked, and leave value undefined until the user chooses.

Loading…
<VStack gap="sm" style={{ maxWidth: 420 }}>
  <Text weight="semibold">Why are you cancelling?</Text>
  <RadioGroup
    value={reason}
    onValueChange={setReason}
    aria-label="Why are you cancelling?"
    options={[
      { value: 'price', label: 'It’s too expensive' },
      { value: 'features', label: 'It’s missing a feature I need' },
      { value: 'switch', label: 'I’m switching to another app' },
      { value: 'other', label: 'Something else' },
    ]}
  />
  {tried && !reason ? <Text size="sm" color="danger">Pick a reason so we can improve.</Text> : null}
  <Button variant="destructive" onPress={() => setTried(true)}>Cancel subscription</Button>
</VStack>

Designs​

In the iOS design an option shows a check mark at the end of its row, as in iOS Settings, instead of a circle. The other designs draw a circle with a dot.

Loading…
<HStack gap="lg" wrap>
  {DESIGNS.map((design) => (
    <VStack key={design} gap="xs" style={{ width: 150 }}>
      <Text size="xs" color="textSecondary">{design}</Text>
      <RadioGroup design={design} defaultValue="dark" aria-label={`Appearance, ${design}`} options={OPTIONS} />
    </VStack>
  ))}
</HStack>

Right to left​

Loading…
<View style={{ direction: 'rtl', maxWidth: 360 }}>
  <RadioGroup
    defaultValue="card"
    aria-label="אמצעי תשלום"
    options={[
      { value: 'card', label: 'כרטיס אשראי', description: 'ויזה, מאסטרקארד, אמקס' },
      { value: 'paypal', label: 'PayPal' },
      { value: 'bit', label: 'ביט', disabled: true },
    ]}
  />
</View>

Radio group, segmented control or select?​

Use a radio group for two to five options that need a description. Use a segmented control for a few short ones in a row, and a select for a long list.

Accessibility​

  • The group has the radiogroup role and takes aria-label. Items are radios with checked and disabled states.
  • On the web, Tab moves into the group to the selected item, and the arrow keys move and select, skipping disabled items.
  • Every row is at least 44pt tall, and pressing the label selects too.
  • Give the group a name with aria-label, or a visible heading it describes: a screen reader reads it when focus enters the group.
  • An item with a custom node as its label needs an accessibilityLabel.

Props​

RadioGroup​

PropTypeDefaultDescription
valuestring—The selected item's value, controlled.
defaultValuestring—The selected value when uncontrolled.
onValueChange(value: string) => void—Called when the user selects an item.
disabledbooleanfalseDisables every item.
orientation'vertical' | 'horizontal''vertical'Lays the items out in a column or a row.
optionsRadioGroupOption[]—Shorthand: { value, label, description?, disabled? } for each option.
childrenReactNode—The RadioGroupItems, when you don't give options.
themeDeepPartial<Theme>—Theme override.
design'brand' | 'ios' | 'material' | 'web' | 'native'from PatineProviderThe look to follow: brand, iOS, Material or web, or 'native' for the platform's own.

RadioGroupItem​

PropTypeDefaultDescription
valuestringrequiredThe value it selects.
labelReactNode—Text next to the indicator.
descriptionReactNode—Secondary text under the label.
disabledbooleanfalseSkips this item.
styleStyleProp<ViewStyle>—The row.
labelStyleStyleProp<TextStyle>—The label.