> Native Solid 2 fork. Original documentation and designs © WorkOS; historical posts retain their original context.

# Radio Group

A set of checkable buttons—known as radio buttons—where no more than one of the buttons can be checked at a time.

## Features

- Full keyboard navigation.

- Supports horizontal/vertical orientation.

- Can be controlled or uncontrolled.

## Anatomy

Import all parts and piece them together.

```jsx
import { RadioGroup } from "@radix-solid/primitives";

export default () => <RadioGroup.Root>

		<RadioGroup.Item value="item">

			<RadioGroup.Indicator />

		</RadioGroup.Item>

	</RadioGroup.Root>;
```

## API Reference

### Root

Contains all the parts of a radio group.

| Prop                                                                                                                                                                    | Type       | Default     |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean`  | `false`     |
| `defaultValue`The value of the radio item that should be checked when initially rendered. Use when you do not need to control the state of the radio items.             | `string`   | —           |
| `value`The controlled value of the radio item to check. Should be used in conjunction with `onValueChange`.                                                             | `string`   | —           |
| `onValueChange`Event handler called when the value changes.                                                                                                             | `function` | —           |
| `disabled`When `true`, prevents the user from interacting with radio items.                                                                                             | `boolean`  | —           |
| `name`The name of the group. Submitted with its owning form as part of a name/value pair.                                                                               | `string`   | —           |
| `required`When `true`, indicates that the user must check a radio item before the owning form can be submitted.                                                         | `boolean`  | —           |
| `orientation`The orientation of the component.                                                                                                                          | `enum`     | `undefined` |
| `dir`The reading direction of the radio group. If omitted, inherits globally from `DirectionProvider` or assumes LTR (left-to-right) reading mode.                      | `enum`     | —           |
| `loop`When `true`, keyboard navigation will loop from last item to first, and vice versa.                                                                               | `boolean`  | `true`      |

| Data attribute    | Values                |
| ----------------- | --------------------- |
| `[data-disabled]` | Present when disabled |

### Item

An item in the group that can be checked. An `input` will also render when used within a `form` to ensure events propagate correctly.

| Prop                                                                                                                                                                    | Type      | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `value`The value given as data when submitted with a `name`.                                                                                                            | `string`  | —       |
| `disabled`When `true`, prevents the user from interacting with the radio item.                                                                                          | `boolean` | —       |
| `required`When `true`, indicates that the user must check the radio item before the owning form can be submitted.                                                       | `boolean` | —       |

| Data attribute    | Values                     |
| ----------------- | -------------------------- |
| `[data-state]`    | `"checked" \| "unchecked"` |
| `[data-disabled]` | Present when disabled      |

### Indicator

Renders when the radio item is in a checked state. You can style this element directly, or you can use it as a wrapper to put an icon into, or both.

| Prop                                                                                                                                                                    | Type      | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `forceMount`Used to force mounting when more control is needed. Useful when controlling animation with Solid-compatible animation libraries.                            | `boolean` | —       |

| Data attribute    | Values                     |
| ----------------- | -------------------------- |
| `[data-state]`    | `"checked" \| "unchecked"` |
| `[data-disabled]` | Present when disabled      |

## Examples

### Decoupling the hidden input

By default, `RadioGroup.Item` renders a visually hidden `input` for form submission. To recompose, move, or exclude that input, you can build each item from its lower-level parts instead.

> **Important:** These parts are unstable and prefixed with `unstable_`, so their API may change in a future release.

- `RadioGroup.unstable_ItemProvider` provides the item state and accepts the item's `value` and `disabled` props.
- `RadioGroup.unstable_ItemTrigger` is the interactive element that wraps `RadioGroup.Indicator`.
- `RadioGroup.unstable_ItemBubbleInput` is the visually hidden input that `RadioGroup.Item` renders by default. Omit it when you don't need form submission.

```jsx
import { RadioGroup } from "@radix-solid/primitives";

export default () => <RadioGroup.Root>

		{["one", "two", "three"].map(value => <RadioGroup.unstable_ItemProvider value={value}>

				<RadioGroup.unstable_ItemTrigger>

					<RadioGroup.Indicator />

				</RadioGroup.unstable_ItemTrigger>

				<RadioGroup.unstable_ItemBubbleInput />

			</RadioGroup.unstable_ItemProvider>)}

	</RadioGroup.Root>;
```

## Accessibility

Adheres to the [Radio Group WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio) and uses [roving tabindex](https://www.w3.org/WAI/ARIA/apg/patterns/radio/examples/radio) to manage focus movement among radio items.

### Keyboard Interactions

| Key          | Description                                                                        |
| ------------ | ---------------------------------------------------------------------------------- |
| `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.                               |
| `ArrowDown`  | Moves focus and checks the next radio item in the group.                           |
| `ArrowRight` | Moves focus and checks the next radio item in the group.                           |
| `ArrowUp`    | Moves focus to the previous radio item in the group.                               |
| `ArrowLeft`  | Moves focus to the previous radio item in the group.                               |