Skip to content
shadcn.io

shadcn.io is not affiliated with official shadcn/ui

Components

Free

Radio Group for React

Keep every option on the page and pick exactly one, for a short setting like a plan or shipping speed. In React with Base UI, arrow keys move the check.

Framework
UI library

Radio buttons leave every option visible, and picking one clears the others.

Use them when the list is short and the form should submit exactly one value. A long list belongs in a Select. In React, Base UI moves focus with the arrow keys and checks the item you move to.

Preview width

Installation

Sign in to get your install command
Free with an account. It carries your token, so the CLI installs everything in one go.
GoogleGitHub
Use email insteadNo credit card

Anatomy

Radio Group anatomy: root, label, item control, indicator, item, item text
RadioGroup
├── RadioGroupLabel
├── RadioGroupItem
│   ├── RadioGroupText
│   └── RadioGroupItemControl
└── RadioGroupIndicator

Usage

import {
  RadioGroup, RadioGroupItem,
} from "@/components/ui/radio-group";
<RadioGroup className="w-fit" defaultValue="comfortable">
  <RadioGroupItem value="default">Default</RadioGroupItem>
  <RadioGroupItem value="comfortable">Comfortable</RadioGroupItem>
  <RadioGroupItem value="compact">Compact</RadioGroupItem>
</RadioGroup>

Accessibility

Tab
Moves focus to either the checked radio item or the first radio item in the group.
Space
When focus is on an unchecked radio item, checks it.
Arrow Down
Moves focus and checks the next radio item in the group.
Arrow Right
Moves focus and checks the next radio item in the group.
Arrow Up
Moves focus to the previous radio item in the group.
Arrow Left
Moves focus to the previous radio item in the group.
End
Go to the end.

Demos

Description

Each option has a second line, not just a name. Field sits the radio and a FieldDescription on one row, so "comfortable" can say that it adds space, instead of hoping the label is enough. Use this when the choice has a consequence people should see before they pick it. Three bare words do not need the extra line.

Preview width

Choice Card

The whole card is the hit target, not only the radio. FieldLabel wraps the Field, with a title and a short line about who the plan is for, and the control sits at the end of the row. Use this for a product, a tier, or anything where the option is a small decision rather than a word in a column. Keep the cards few.

Preview width

Fieldset

The group itself needs a name. FieldSet and FieldLegend label the question, subscription plan, and FieldDescription says why the yearly option exists. The radios are the answers under that legend. Use a fieldset when the question would otherwise be invisible to assistive tech, or when several groups on the page would blur together.

Preview width

Disabled

One option is switched off and the others still work. The group keeps a different option selected, which is what you want when a plan is unavailable but a choice is still required. Set disabled on that RadioGroupItem, or on the group to lock every option. On React Aria the prop is isDisabled instead, and data-disabled on the Field keeps the row styling in agreement.

Preview width

Invalid

The options are flagged invalid, and data-invalid on the field turns on the error styling. The legend still only says what the group is for, so add a sentence that says what failed. Color on the radios is not the message. Set aria-invalid on each RadioGroupItem, or isInvalid on RadioGroup for React Aria.

Preview width

Rtl

The group sets dir to rtl, and the Arabic labels lead, with the description following. Use this to check a translated form, not as a variant you render only for one language. The row should flip with its parent. If this group must flip while the rest of the document stays left to right, set dir on the group itself rather than on the page.

Preview width

FAQ

How do I control the selected Radio Group value in React?

A Radio Group selects exactly one string, so keep that string in state and pass it back, or leave the group uncontrolled when the first choice is enough. Each RadioGroupItem has its own value. Pass value, and onValueChange receives the new value. Set defaultValue when the group should manage itself.

How do I submit a Radio Group with a form?

Set name on Radio Group to the field name the form should receive. The checked item's value is submitted under that name, not the visible label. Keep the group inside the form element so the browser includes it. An unchecked group submits nothing.

Why is my Radio Group label not clickable?

The item and its text must be associated, even though the markup is not the same on every base, and clicking the text then checks the item. Follow the Description demo for the markup on your base. Do not put the label inside RadioGroupItem. Give the item an id and point FieldLabel at it with htmlFor.

Can I use a Radio Group from the keyboard?

Yes, Tab moves focus to the checked item, or to the first item when none is checked. The arrow keys move to another item and check it, and Space checks the item that has focus. End moves to the last item, and Tab then leaves the group.

How do I show a Radio Group as invalid with Base UI?

Show the error on the field, not only with color, because color alone is not the error. Keep a text message in the field. The Invalid demo pairs the group with Field so that message sits with the options. Set aria-invalid on each RadioGroupItem and data-invalid on the surrounding Field.

How do I disable a Radio Group?

Disable the whole set or a single option. A disabled item stays visible but cannot be checked, and the Disabled demo leaves one item disabled and selects another. Set disabled on Radio Group for every item, or on one RadioGroupItem.

Should I use a Radio Group or a Segment Group?

Use a Radio Group when each option needs a label, a description, or its own place in a form. Use a Segment Group for a short row of choices with a sliding indicator. Use a Checkbox when more than one option can be on at the same time.

How do I install Radio Group in React?

Run the command in the Installation section above. It adds Radio Group and its parts to your ui folder. Import from that folder when the command finishes, instead of copying the source by hand, and rerun the command later if you want the latest files. The command uses the shadcn CLI.

API Reference

RadioGroup

data-slot="radio-group"

PropType
render?ReactElement | ((props: object, state: object) => ReactElement)

Replace the host element or compose it with another component.

Type
ReactElement | ((props: object, state: object) => ReactElement)
className?string

Merged with the part's classes.

RadioGroupItem

<span> data-slot="radio-group-item"

PropType
valueValue

The unique identifying value of the radio in a group.

disabled?boolean

Whether the component should ignore user interaction.

inputRef?React.Ref<HTMLInputElement>

A ref to access the hidden input element.

Type
React.Ref<HTMLInputElement>
nativeButton?boolean

Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.

Default
false
readOnly?boolean

Whether the user should be unable to select the radio button.

required?boolean

Whether the user must choose a value before submitting a form.

render?ReactElement | ((props: object, state: object) => ReactElement)

Replace the host element or compose it with another component.

Type
ReactElement | ((props: object, state: object) => ReactElement)
className?string

Merged with the part's classes.

RadioGroupText

data-slot="radio-group-item-text"

PropType
nativeLabel?boolean

Whether the component renders a native <label> element when replacing it via the render prop. Set to false if the rendered element is not a label (for example, <div>). This is useful to avoid inheriting label behaviors on <button> controls (such as <Select.Trigger> and <Combobox.Trigger>), including avoiding :hover on the button when hovering the label, and preventing clicks on the label from firing on the button.

Default
true
render?ReactElement | ((props: object, state: object) => ReactElement)

Replace the host element or compose it with another component.

Type
ReactElement | ((props: object, state: object) => ReactElement)

RadioGroupLabel

data-slot="radio-group-label"

PropType
nativeLabel?boolean

Whether the component renders a native <label> element when replacing it via the render prop. Set to false if the rendered element is not a label (for example, <div>). This is useful to avoid inheriting label behaviors on <button> controls (such as <Select.Trigger> and <Combobox.Trigger>), including avoiding :hover on the button when hovering the label, and preventing clicks on the label from firing on the button.

Default
true
render?ReactElement | ((props: object, state: object) => ReactElement)

Replace the host element or compose it with another component.

Type
ReactElement | ((props: object, state: object) => ReactElement)

With other components

  • Free

    Field

    Inputs

    Label and helper text

  • Free

    Label

    Inputs

    Click the words

  • Free

    Card

    Layout

    Plan as a card

  • Free

    Button

    Buttons

    Submit the form

  • Free

    Item

    Layout

    Row in a list

  • Free

    Tooltip

    Overlays

    Explain one option

All 105 components9 radio group examples