---
title: Radio group
description: Radio Group allows users to select a single option from a list of mutually exclusive choices.
category: Forms
related: [Checkbox, Switch, Label, Container]
commonPatterns: [form-radio-selection, settings-radio, single-choice]
---

Source: https://clickhouse.design/click-ui/radiogroup

# Radio group

Radio Group provides a set of radio buttons that allow users to select a single option from multiple choices. The options are mutually exclusive - selecting one deselects the others.

## Example

## Props

| Prop          | Type                         | Default value  | Description                                                                          |
| ------------- | ---------------------------- | -------------- | ------------------------------------------------------------------------------------ |
| label         | `ReactNode`                  | `undefined`    | Label text or content displayed above the radio group                                |
| error         | `ReactNode`                  | `undefined`    | Error message or content displayed when validation fails                             |
| inline        | `boolean`                    | `true`         | Whether radio items are displayed inline (horizontally) or stacked (vertically)      |
| orientation   | `"vertical" \| "horizontal"` | `"horizontal"` | Layout orientation - whether items are arranged vertically or horizontally           |
| dir           | `"start" \| "end"`           | `"start"`      | Direction/position of labels relative to radio buttons (start = before, end = after) |
| itemDir       | `"rtl" \| "ltr"`             | `"ltr"`        | Text direction for radio items - left-to-right or right-to-left                      |
| disabled      | `boolean`                    | `false`        | Whether the entire radio group is disabled                                           |
| value         | `string`                     | `undefined`    | Currently selected value for controlled radio groups                                 |
| defaultValue  | `string`                     | `undefined`    | Default selected value for uncontrolled radio groups                                 |
| onValueChange | `(value: string) => void`    | `undefined`    | Callback function called when the selected value changes. Receives the new value.    |

```tsx
import { RadioGroup } from '@clickhouse/click-ui'
import { useState } from 'react'

function MyRadioGroup() {
const [value, setValue] = useState('option1')
return (
  <RadioGroup label="Select an option" value={value} onValueChange={setValue}>
    <RadioGroup.Item value="option1" label="Option 1" />
    <RadioGroup.Item value="option2" label="Option 2" />
    <RadioGroup.Item value="option3" label="Option 3" />
  </RadioGroup>
)
}
```

### RadioGroup.Item Props

| Prop     | Type        | Default value | Description                                              |
| -------- | ----------- | ------------- | -------------------------------------------------------- |
| value    | `string`    | `undefined`   | Unique value for this radio option. Required.            |
| label    | `ReactNode` | `undefined`   | Label text or content displayed next to the radio button |
| disabled | `boolean`   | `false`       | Whether this specific radio item is disabled             |

```tsx
<RadioGroup.Item value="option1" label="Option 1" />
```

## Quick start

```tsx
import { RadioGroup } from '@clickhouse/click-ui'
import { useState } from 'react'

function MyRadioGroup() {
const [value, setValue] = useState('option1')
return (
  <RadioGroup label="Select an option" value={value} onValueChange={setValue}>
    <RadioGroup.Item value="option1" label="Option 1" />
    <RadioGroup.Item value="option2" label="Option 2" />
    <RadioGroup.Item value="option3" label="Option 3" />
  </RadioGroup>
)
}
```

## Related components

- **Checkbox**: For selecting one or more items from a list.
- **Switch**: For toggle switches between two states.
- **Label**: Provides accessible labels for radio groups.
- **Container**: For organizing radio groups within layouts.

## Common use cases

### Form radio selection

```tsx
import { RadioGroup } from '@clickhouse/click-ui'
import { useState } from 'react'

function FormRadioSelection() {
const [plan, setPlan] = useState('basic')
return (
  <RadioGroup label='Select a plan' value={plan} onValueChange={setPlan}>
    <RadioGroup.Item value='basic' label='Basic Plan' />
    <RadioGroup.Item value='pro' label='Pro Plan' />
    <RadioGroup.Item value='enterprise' label='Enterprise Plan' />
  </RadioGroup>
)
}
```

### Settings radio

```tsx
import { RadioGroup } from '@clickhouse/click-ui'
import { useState } from 'react'

function SettingsRadio() {
const [theme, setTheme] = useState('light')
return (
  <RadioGroup label='Theme' value={theme} onValueChange={setTheme}>
    <RadioGroup.Item value='light' label='Light' />
    <RadioGroup.Item value='dark' label='Dark' />
    <RadioGroup.Item value='auto' label='Auto' />
  </RadioGroup>
)
}
```

### Vertical layout

```tsx
import { RadioGroup } from '@clickhouse/click-ui'
import { useState } from 'react'

function VerticalRadioGroup() {
const [value, setValue] = useState('option1')
return (
  <RadioGroup label='Vertical options' value={value} onValueChange={setValue} inline={false}>
    <RadioGroup.Item value='option1' label='Option 1' />
    <RadioGroup.Item value='option2' label='Option 2' />
    <RadioGroup.Item value='option3' label='Option 3' />
  </RadioGroup>
)
}
```

### With error state